vc_sm: Let it support to build in the non-src folder

If we build the kernel with "-O=$non-src-folder", this driver will
introdcue a building error because of the header's location.

Signed-off-by: Hui Wang <hui.wang@canonical.com>

.clang-format

@@ -86,8 +86,6 @@ ForEachMacros:
   - 'bio_for_each_segment_all'
   - 'bio_list_for_each'
   - 'bip_for_each_vec'
-  - 'bitmap_for_each_clear_region'
-  - 'bitmap_for_each_set_region'
   - 'blkg_for_each_descendant_post'
   - 'blkg_for_each_descendant_pre'
   - 'blk_queue_for_each_rl'
@@ -117,7 +115,6 @@ ForEachMacros:
   - 'drm_client_for_each_connector_iter'
   - 'drm_client_for_each_modeset'
   - 'drm_connector_for_each_possible_encoder'
-  - 'drm_for_each_bridge_in_chain'
   - 'drm_for_each_connector_iter'
   - 'drm_for_each_crtc'
   - 'drm_for_each_encoder'
@@ -139,10 +136,9 @@ ForEachMacros:
   - 'for_each_bio'
   - 'for_each_board_func_rsrc'
   - 'for_each_bvec'
-  - 'for_each_card_auxs'
-  - 'for_each_card_auxs_safe'
   - 'for_each_card_components'
-  - 'for_each_card_pre_auxs'
+  - 'for_each_card_links'
+  - 'for_each_card_links_safe'
   - 'for_each_card_prelinks'
   - 'for_each_card_rtds'
   - 'for_each_card_rtds_safe'
@@ -170,7 +166,6 @@ ForEachMacros:
   - 'for_each_dpcm_fe'
   - 'for_each_drhd_unit'
   - 'for_each_dss_dev'
-  - 'for_each_efi_handle'
   - 'for_each_efi_memory_desc'
   - 'for_each_efi_memory_desc_in_map'
   - 'for_each_element'
@@ -195,7 +190,6 @@ ForEachMacros:
   - 'for_each_lru'
   - 'for_each_matching_node'
   - 'for_each_matching_node_and_match'
-  - 'for_each_member'
   - 'for_each_memblock'
   - 'for_each_memblock_type'
   - 'for_each_memcg_cache_index'
@@ -206,11 +200,9 @@ ForEachMacros:
   - 'for_each_msi_entry'
   - 'for_each_msi_entry_safe'
   - 'for_each_net'
-  - 'for_each_net_continue_reverse'
   - 'for_each_netdev'
   - 'for_each_netdev_continue'
   - 'for_each_netdev_continue_rcu'
-  - 'for_each_netdev_continue_reverse'
   - 'for_each_netdev_feature'
   - 'for_each_netdev_in_bond_rcu'
   - 'for_each_netdev_rcu'
@@ -262,10 +254,10 @@ ForEachMacros:
   - 'for_each_reserved_mem_region'
   - 'for_each_rtd_codec_dai'
   - 'for_each_rtd_codec_dai_rollback'
-  - 'for_each_rtd_components'
+  - 'for_each_rtdcom'
+  - 'for_each_rtdcom_safe'
   - 'for_each_set_bit'
   - 'for_each_set_bit_from'
-  - 'for_each_set_clump8'
   - 'for_each_sg'
   - 'for_each_sg_dma_page'
   - 'for_each_sg_page'
@@ -275,7 +267,6 @@ ForEachMacros:
   - 'for_each_subelement_id'
   - '__for_each_thread'
   - 'for_each_thread'
-  - 'for_each_wakeup_source'
   - 'for_each_zone'
   - 'for_each_zone_zonelist'
   - 'for_each_zone_zonelist_nodemask'
@@ -339,7 +330,6 @@ ForEachMacros:
   - 'list_for_each'
   - 'list_for_each_codec'
   - 'list_for_each_codec_safe'
-  - 'list_for_each_continue'
   - 'list_for_each_entry'
   - 'list_for_each_entry_continue'
   - 'list_for_each_entry_continue_rcu'
@@ -361,7 +351,6 @@ ForEachMacros:
   - 'llist_for_each_entry'
   - 'llist_for_each_entry_safe'
   - 'llist_for_each_safe'
-  - 'mci_for_each_dimm'
   - 'media_device_for_each_entity'
   - 'media_device_for_each_intf'
   - 'media_device_for_each_link'
@@ -455,16 +444,10 @@ ForEachMacros:
   - 'virtio_device_for_each_vq'
   - 'xa_for_each'
   - 'xa_for_each_marked'
-  - 'xa_for_each_range'
   - 'xa_for_each_start'
   - 'xas_for_each'
   - 'xas_for_each_conflict'
   - 'xas_for_each_marked'
-  - 'xbc_array_for_each_value'
-  - 'xbc_for_each_key_value'
-  - 'xbc_node_for_each_array_value'
-  - 'xbc_node_for_each_child'
-  - 'xbc_node_for_each_key_value'
   - 'zorro_for_each_dev'
 
 #IncludeBlocks: Preserve # Unknown to clang-format-5.0

.gitattributes

@@ -1,4 +1,2 @@
 *.c   diff=cpp
 *.h   diff=cpp
-*.dtsi diff=dts
-*.dts  diff=dts

.gitignore

@@ -35,6 +35,7 @@
 *.mod.c
 *.o
 *.o.*
+*.order
 *.patch
 *.s
 *.so
@@ -46,7 +47,6 @@
 *.xz
 Module.symvers
 modules.builtin
-modules.order
 
 #
 # Top-level generic files
@@ -61,7 +61,6 @@ modules.order
 /System.map
 /Module.markers
 /modules.builtin.modinfo
-/modules.nsdeps
 
 #
 # RPM spec file (make rpm-pkg)

.mailmap

@@ -18,7 +18,6 @@ Aleksey Gorelov <aleksey_gorelov@phoenix.com>
 Aleksandar Markovic <aleksandar.markovic@mips.com> <aleksandar.markovic@imgtec.com>
 Alex Shi <alex.shi@linux.alibaba.com> <alex.shi@intel.com>
 Alex Shi <alex.shi@linux.alibaba.com> <alex.shi@linaro.org>
-Alexandre Belloni <alexandre.belloni@bootlin.com> <alexandre.belloni@free-electrons.com>
 Alexei Starovoitov <ast@kernel.org> <ast@plumgrid.com>
 Alexei Starovoitov <ast@kernel.org> <alexei.starovoitov@gmail.com>
 Alexei Starovoitov <ast@kernel.org> <ast@fb.com>
@@ -28,14 +27,11 @@ Andi Shyti <andi@etezian.org> <andi.shyti@samsung.com>
 Andreas Herrmann <aherrman@de.ibm.com>
 Andrey Ryabinin <ryabinin.a.a@gmail.com> <a.ryabinin@samsung.com>
 Andrew Morton <akpm@linux-foundation.org>
-Andrew Murray <amurray@thegoodpenguin.co.uk> <andrew.murray@arm.com>
-Andrew Murray <amurray@thegoodpenguin.co.uk> <amurray@embedded-bits.co.uk>
 Andrew Vasquez <andrew.vasquez@qlogic.com>
 Andy Adamson <andros@citi.umich.edu>
 Antoine Tenart <antoine.tenart@free-electrons.com>
 Antonio Ospite <ao2@ao2.it> <ao2@amarulasolutions.com>
 Archit Taneja <archit@ti.com>
-Ard Biesheuvel <ardb@kernel.org> <ard.biesheuvel@linaro.org>
 Arnaud Patard <arnaud.patard@rtp-net.org>
 Arnd Bergmann <arnd@arndb.de>
 Axel Dyks <xl@xlsigned.net>
@@ -51,8 +47,6 @@ Boris Brezillon <bbrezillon@kernel.org> <b.brezillon.dev@gmail.com>
 Boris Brezillon <bbrezillon@kernel.org> <b.brezillon@overkiz.com>
 Brian Avery <b.avery@hp.com>
 Brian King <brking@us.ibm.com>
-Chao Yu <chao@kernel.org> <chao2.yu@samsung.com>
-Chao Yu <chao@kernel.org> <yuchao0@huawei.com>
 Christoph Hellwig <hch@lst.de>
 Christophe Ricard <christophe.ricard@gmail.com>
 Corey Minyard <minyard@acm.org>
@@ -69,7 +63,6 @@ Dengcheng Zhu <dzhu@wavecomp.com> <dengcheng.zhu@mips.com>
 Dengcheng Zhu <dzhu@wavecomp.com> <dengcheng.zhu@imgtec.com>
 Dengcheng Zhu <dzhu@wavecomp.com> <dczhu@mips.com>
 Dengcheng Zhu <dzhu@wavecomp.com> <dengcheng.zhu@gmail.com>
-<dev.kurt@vandijck-laurijssen.be> <kurt.van.dijck@eia.be>
 Dmitry Eremin-Solenikov <dbaryshkov@gmail.com>
 Dmitry Safonov <0x7f454c46@gmail.com> <dsafonov@virtuozzo.com>
 Dmitry Safonov <0x7f454c46@gmail.com> <d.safonov@partner.samsung.com>
@@ -77,7 +70,6 @@ Dmitry Safonov <0x7f454c46@gmail.com> <dima@arista.com>
 Domen Puncer <domen@coderock.org>
 Douglas Gilbert <dougg@torque.net>
 Ed L. Cashin <ecashin@coraid.com>
-Erik Kaneda <erik.kaneda@intel.com> <erik.schmauss@intel.com>
 Evgeniy Polyakov <johnpol@2ka.mipt.ru>
 Felipe W Damasio <felipewd@terra.com.br>
 Felix Kuhling <fxkuehl@gmx.de>
@@ -88,8 +80,6 @@ Frank Rowand <frowand.list@gmail.com> <frowand@mvista.com>
 Frank Rowand <frowand.list@gmail.com> <frank.rowand@am.sony.com>
 Frank Rowand <frowand.list@gmail.com> <frank.rowand@sonymobile.com>
 Frank Zago <fzago@systemfabricworks.com>
-Gao Xiang <xiang@kernel.org> <gaoxiang25@huawei.com>
-Gao Xiang <xiang@kernel.org> <hsiangkao@aol.com>
 Greg Kroah-Hartman <greg@echidna.(none)>
 Greg Kroah-Hartman <gregkh@suse.de>
 Greg Kroah-Hartman <greg@kroah.com>
@@ -100,27 +90,16 @@ Henrik Kretzschmar <henne@nachtwindheim.de>
 Henrik Rydberg <rydberg@bitmath.org>
 Herbert Xu <herbert@gondor.apana.org.au>
 Jacob Shin <Jacob.Shin@amd.com>
-Jaegeuk Kim <jaegeuk@kernel.org> <jaegeuk@google.com>
-Jaegeuk Kim <jaegeuk@kernel.org> <jaegeuk@motorola.com>
-Jaegeuk Kim <jaegeuk@kernel.org> <jaegeuk.kim@samsung.com>
-Jakub Kicinski <kuba@kernel.org> <jakub.kicinski@netronome.com>
 James Bottomley <jejb@mulgrave.(none)>
 James Bottomley <jejb@titanic.il.steeleye.com>
 James E Wilson <wilson@specifix.com>
 James Hogan <jhogan@kernel.org> <james.hogan@imgtec.com>
 James Hogan <jhogan@kernel.org> <james@albanarts.com>
 James Ketrenos <jketreno@io.(none)>
-Jan Glauber <jan.glauber@gmail.com> <jang@de.ibm.com>
-Jan Glauber <jan.glauber@gmail.com> <jang@linux.vnet.ibm.com>
-Jan Glauber <jan.glauber@gmail.com> <jglauber@cavium.com>
 Jason Gunthorpe <jgg@ziepe.ca> <jgg@mellanox.com>
 Jason Gunthorpe <jgg@ziepe.ca> <jgunthorpe@obsidianresearch.com>
 Javi Merino <javi.merino@kernel.org> <javi.merino@arm.com>
 <javier@osg.samsung.com> <javier.martinez@collabora.co.uk>
-Jayachandran C <c.jayachandran@gmail.com> <jayachandranc@netlogicmicro.com>
-Jayachandran C <c.jayachandran@gmail.com> <jchandra@broadcom.com>
-Jayachandran C <c.jayachandran@gmail.com> <jchandra@digeo.com>
-Jayachandran C <c.jayachandran@gmail.com> <jnair@caviumnetworks.com>
 Jean Tourrilhes <jt@hpl.hp.com>
 <jean-philippe@linaro.org> <jean-philippe.brucker@arm.com>
 Jeff Garzik <jgarzik@pretzel.yyz.us>
@@ -142,7 +121,6 @@ Juha Yrjola <at solidboot.com>
 Juha Yrjola <juha.yrjola@nokia.com>
 Juha Yrjola <juha.yrjola@solidboot.com>
 Julien Thierry <julien.thierry.kdev@gmail.com> <julien.thierry@arm.com>
-Kamil Konieczny <k.konieczny@samsung.com> <k.konieczny@partner.samsung.com>
 Kay Sievers <kay.sievers@vrfy.org>
 Kenneth W Chen <kenneth.w.chen@intel.com>
 Konstantin Khlebnikov <koct9i@gmail.com> <k.khlebnikov@samsung.com>
@@ -158,7 +136,6 @@ Linus Lüssing <linus.luessing@c0d3.blue> <linus.luessing@web.de>
 Linus Lüssing <linus.luessing@c0d3.blue> <linus.luessing@ascom.ch>
 Li Yang <leoyang.li@nxp.com> <leo@zh-kernel.org>
 Li Yang <leoyang.li@nxp.com> <leoli@freescale.com>
-Lukasz Luba <lukasz.luba@arm.com> <l.luba@partner.samsung.com>
 Maciej W. Rozycki <macro@mips.com> <macro@imgtec.com>
 Marc Zyngier <maz@kernel.org> <marc.zyngier@arm.com>
 Marcin Nowakowski <marcin.nowakowski@mips.com> <marcin.nowakowski@imgtec.com>
@@ -166,7 +143,6 @@ Mark Brown <broonie@sirena.org.uk>
 Mark Yao <markyao0591@gmail.com> <mark.yao@rock-chips.com>
 Martin Kepplinger <martink@posteo.de> <martin.kepplinger@theobroma-systems.com>
 Martin Kepplinger <martink@posteo.de> <martin.kepplinger@ginzinger.com>
-Martin Kepplinger <martink@posteo.de> <martin.kepplinger@puri.sm>
 Mathieu Othacehe <m.othacehe@gmail.com>
 Matthew Wilcox <willy@infradead.org> <matthew.r.wilcox@intel.com>
 Matthew Wilcox <willy@infradead.org> <matthew@wil.cx>
@@ -202,22 +178,11 @@ Morten Welinder <welinder@darter.rentec.com>
 Morten Welinder <welinder@troll.com>
 Mythri P K <mythripk@ti.com>
 Nguyen Anh Quynh <aquynh@gmail.com>
-Nicolas Ferre <nicolas.ferre@microchip.com> <nicolas.ferre@atmel.com>
 Nicolas Pitre <nico@fluxnic.net> <nicolas.pitre@linaro.org>
 Nicolas Pitre <nico@fluxnic.net> <nico@linaro.org>
-Oleksij Rempel <linux@rempel-privat.de> <bug-track@fisher-privat.net>
-Oleksij Rempel <linux@rempel-privat.de> <external.Oleksij.Rempel@de.bosch.com>
-Oleksij Rempel <linux@rempel-privat.de> <fixed-term.Oleksij.Rempel@de.bosch.com>
-Oleksij Rempel <linux@rempel-privat.de> <o.rempel@pengutronix.de>
-Oleksij Rempel <linux@rempel-privat.de> <ore@pengutronix.de>
 Paolo 'Blaisorblade' Giarrusso <blaisorblade@yahoo.it>
 Patrick Mochel <mochel@digitalimplant.org>
-Paul Burton <paulburton@kernel.org> <paul.burton@imgtec.com>
-Paul Burton <paulburton@kernel.org> <paul.burton@mips.com>
-Paul E. McKenney <paulmck@kernel.org> <paulmck@linux.ibm.com>
-Paul E. McKenney <paulmck@kernel.org> <paulmck@linux.vnet.ibm.com>
-Paul E. McKenney <paulmck@kernel.org> <paul.mckenney@linaro.org>
-Paul E. McKenney <paulmck@kernel.org> <paulmck@us.ibm.com>
+Paul Burton <paul.burton@mips.com> <paul.burton@imgtec.com>
 Peter A Jonsson <pj@ludd.ltu.se>
 Peter Oruba <peter@oruba.de>
 Peter Oruba <peter.oruba@amd.com>
@@ -225,9 +190,11 @@ Pratyush Anand <pratyush.anand@gmail.com> <pratyush.anand@st.com>
 Praveen BP <praveenbp@ti.com>
 Punit Agrawal <punitagrawal@gmail.com> <punit.agrawal@arm.com>
 Qais Yousef <qsyousef@gmail.com> <qais.yousef@imgtec.com>
-Quentin Monnet <quentin@isovalent.com> <quentin.monnet@netronome.com>
-Quentin Perret <qperret@qperret.net> <quentin.perret@arm.com>
-Rafael J. Wysocki <rjw@rjwysocki.net> <rjw@sisk.pl>
+Oleksij Rempel <linux@rempel-privat.de> <bug-track@fisher-privat.net>
+Oleksij Rempel <linux@rempel-privat.de> <external.Oleksij.Rempel@de.bosch.com>
+Oleksij Rempel <linux@rempel-privat.de> <fixed-term.Oleksij.Rempel@de.bosch.com>
+Oleksij Rempel <linux@rempel-privat.de> <o.rempel@pengutronix.de>
+Oleksij Rempel <linux@rempel-privat.de> <ore@pengutronix.de>
 Rajesh Shah <rajesh.shah@intel.com>
 Ralf Baechle <ralf@linux-mips.org>
 Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
@@ -252,7 +219,6 @@ Shuah Khan <shuah@kernel.org> <shuahkhan@gmail.com>
 Shuah Khan <shuah@kernel.org> <shuah.khan@hp.com>
 Shuah Khan <shuah@kernel.org> <shuahkh@osg.samsung.com>
 Shuah Khan <shuah@kernel.org> <shuah.kh@samsung.com>
-Simon Arlott <simon@octiron.net> <simon@fire.lp0.eu>
 Simon Kelley <simon@thekelleys.org.uk>
 Stéphane Witzmann <stephane.witzmann@ubpmes.univ-bpclermont.fr>
 Stephen Hemminger <shemminger@osdl.org>
@@ -263,8 +229,6 @@ Sumit Semwal <sumit.semwal@ti.com>
 Tejun Heo <htejun@gmail.com>
 Thomas Graf <tgraf@suug.ch>
 Thomas Pedersen <twp@codeaurora.org>
-Tiezhu Yang <yangtiezhu@loongson.cn> <kernelpatch@126.com>
-Todor Tomov <todor.too@gmail.com> <todor.tomov@linaro.org>
 Tony Luck <tony.luck@intel.com>
 TripleX Chung <xxx.phy@gmail.com> <zhongyu@18mail.cn>
 TripleX Chung <xxx.phy@gmail.com> <triplex@zh-kernel.org>
@@ -279,7 +243,6 @@ Vinod Koul <vkoul@kernel.org> <vkoul@infradead.org>
 Viresh Kumar <vireshk@kernel.org> <viresh.kumar@st.com>
 Viresh Kumar <vireshk@kernel.org> <viresh.linux@gmail.com>
 Viresh Kumar <vireshk@kernel.org> <viresh.kumar2@arm.com>
-Vivien Didelot <vivien.didelot@gmail.com> <vivien.didelot@savoirfairelinux.com>
 Vlad Dogaru <ddvlad@gmail.com> <vlad.dogaru@intel.com>
 Vladimir Davydov <vdavydov.dev@gmail.com> <vdavydov@virtuozzo.com>
 Vladimir Davydov <vdavydov.dev@gmail.com> <vdavydov@parallels.com>
@@ -291,5 +254,3 @@ Gustavo Padovan <gustavo@las.ic.unicamp.br>
 Gustavo Padovan <padovan@profusion.mobi>
 Changbin Du <changbin.du@intel.com> <changbin.du@intel.com>
 Changbin Du <changbin.du@intel.com> <changbin.du@gmail.com>
-Steve Wise <larrystevenwise@gmail.com> <swise@chelsio.com>
-Steve Wise <larrystevenwise@gmail.com> <swise@opengridcomputing.com>

COPYING

@@ -16,5 +16,3 @@ In addition, other licenses may also apply. Please see:
 	Documentation/process/license-rules.rst
 
 for more details.
-
-All contributions to the Linux Kernel are subject to this COPYING file.

CREDITS

@@ -567,11 +567,6 @@ D: Original author of Amiga FFS filesystem
 S: Orlando, Florida
 S: USA
 
-N: Paul Burton
-E: paulburton@kernel.org
-W: https://pburton.com
-D: MIPS maintainer 2018-2020
-
 N: Lennert Buytenhek
 E: kernel@wantstofly.org
 D: Original (2.4) rewrite of the ethernet bridging code
@@ -756,7 +751,7 @@ S: Santa Cruz, California
 S: USA
 
 N: Luis Correia
-E: luisfcorreia@gmail.com
+E: lfcorreia@users.sf.net
 D: Ralink rt2x00 WLAN driver
 S: Belas, Portugal
 
@@ -1642,10 +1637,6 @@ S: Panoramastrasse 18
 S: D-69126 Heidelberg
 S: Germany
 
-N: Simon Horman
-M: horms@verge.net.au
-D: Renesas ARM/ARM64 SoC maintainer
-
 N: Christopher Horn
 E: chorn@warwick.net
 D: Miscellaneous sysctl hacks
@@ -1880,9 +1871,8 @@ S: The Netherlands
 
 N: Martin Kepplinger
 E: martink@posteo.de
-E: martin.kepplinger@puri.sm
+E: martin.kepplinger@ginzinger.com
 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
@@ -3307,9 +3297,7 @@ S: France
 N: Aleksa Sarai
 E: cyphar@cyphar.com
 W: https://www.cyphar.com/
-D: /sys/fs/cgroup/pids
-D: openat2(2)
-S: Sydney, Australia
+D: `pids` cgroup subsystem
 
 N: Dipankar Sarma
 E: dipankar@in.ibm.com

Documentation/ABI/obsolete/sysfs-selinux-disable

@@ -1,26 +0,0 @@
-What:		/sys/fs/selinux/disable
-Date:		April 2005 (predates git)
-KernelVersion:	2.6.12-rc2 (predates git)
-Contact:	selinux@vger.kernel.org
-Description:
-
-	The selinuxfs "disable" node allows SELinux to be disabled at runtime
-	prior to a policy being loaded into the kernel.  If disabled via this
-	mechanism, SELinux will remain disabled until the system is rebooted.
-
-	The preferred method of disabling SELinux is via the "selinux=0" boot
-	parameter, but the selinuxfs "disable" node was created to make it
-	easier for systems with primitive bootloaders that did not allow for
-	easy modification of the kernel command line.  Unfortunately, allowing
-	for SELinux to be disabled at runtime makes it difficult to secure the
-	kernel's LSM hooks using the "__ro_after_init" feature.
-
-	Thankfully, the need for the SELinux runtime disable appears to be
-	gone, the default Kconfig configuration disables this selinuxfs node,
-	and only one of the major distributions, Fedora, supports disabling
-	SELinux at runtime.  Fedora is in the process of removing the
-	selinuxfs "disable" node and once that is complete we will start the
-	slow process of removing this code from the kernel.
-
-	More information on /sys/fs/selinux/disable can be found under the
-	CONFIG_SECURITY_SELINUX_DISABLE Kconfig option.

Documentation/ABI/stable/sysfs-bus-w1

@@ -6,6 +6,6 @@ Description:	Bus scanning interval, microseconds component.
 		control systems are attached/generate presence for as short as
 		100 ms - hence the tens-to-hundreds milliseconds scan intervals
 		are required.
-		see Documentation/w1/w1-generic.rst for detailed information.
+		see Documentation/w1/w1.generic for detailed information.
 Users:		any user space application which wants to know bus scanning
 		interval

Documentation/ABI/stable/sysfs-class-infiniband

@@ -314,6 +314,25 @@ Description:
 		board_id:	(RO) Manufacturing board ID
 
 
+sysfs interface for Chelsio T3 RDMA Driver (cxgb3)
+--------------------------------------------------
+
+What:		/sys/class/infiniband/cxgb3_X/hw_rev
+What:		/sys/class/infiniband/cxgb3_X/hca_type
+What:		/sys/class/infiniband/cxgb3_X/board_id
+Date:		Feb, 2007
+KernelVersion:	v2.6.21
+Contact:	linux-rdma@vger.kernel.org
+Description:
+		hw_rev:		(RO) Hardware revision number
+
+		hca_type:	(RO) HCA type. Here it is a driver short name.
+				It should normally match the name in its bus
+				driver structure (e.g.  pci_driver::name).
+
+		board_id:	(RO) Manufacturing board id
+
+
 sysfs interface for Mellanox ConnectX HCA IB driver (mlx4)
 ----------------------------------------------------------
 

Documentation/ABI/stable/sysfs-class-tpm

@@ -1,7 +1,7 @@
 What:		/sys/class/tpm/tpmX/device/
 Date:		April 2005
 KernelVersion:	2.6.12
-Contact:	linux-integrity@vger.kernel.org
+Contact:	tpmdd-devel@lists.sf.net
 Description:	The device/ directory under a specific TPM instance exposes
 		the properties of that TPM chip
 
@@ -9,7 +9,7 @@ Description:	The device/ directory under a specific TPM instance exposes
 What:		/sys/class/tpm/tpmX/device/active
 Date:		April 2006
 KernelVersion:	2.6.17
-Contact:	linux-integrity@vger.kernel.org
+Contact:	tpmdd-devel@lists.sf.net
 Description:	The "active" property prints a '1' if the TPM chip is accepting
 		commands. An inactive TPM chip still contains all the state of
 		an active chip (Storage Root Key, NVRAM, etc), and can be
@@ -21,7 +21,7 @@ Description:	The "active" property prints a '1' if the TPM chip is accepting
 What:		/sys/class/tpm/tpmX/device/cancel
 Date:		June 2005
 KernelVersion:	2.6.13
-Contact:	linux-integrity@vger.kernel.org
+Contact:	tpmdd-devel@lists.sf.net
 Description:	The "cancel" property allows you to cancel the currently
 		pending TPM command. Writing any value to cancel will call the
 		TPM vendor specific cancel operation.
@@ -29,7 +29,7 @@ Description:	The "cancel" property allows you to cancel the currently
 What:		/sys/class/tpm/tpmX/device/caps
 Date:		April 2005
 KernelVersion:	2.6.12
-Contact:	linux-integrity@vger.kernel.org
+Contact:	tpmdd-devel@lists.sf.net
 Description:	The "caps" property contains TPM manufacturer and version info.
 
 		Example output:
@@ -46,7 +46,7 @@ Description:	The "caps" property contains TPM manufacturer and version info.
 What:		/sys/class/tpm/tpmX/device/durations
 Date:		March 2011
 KernelVersion:	3.1
-Contact:	linux-integrity@vger.kernel.org
+Contact:	tpmdd-devel@lists.sf.net
 Description:	The "durations" property shows the 3 vendor-specific values
 		used to wait for a short, medium and long TPM command. All
 		TPM commands are categorized as short, medium or long in
@@ -69,7 +69,7 @@ Description:	The "durations" property shows the 3 vendor-specific values
 What:		/sys/class/tpm/tpmX/device/enabled
 Date:		April 2006
 KernelVersion:	2.6.17
-Contact:	linux-integrity@vger.kernel.org
+Contact:	tpmdd-devel@lists.sf.net
 Description:	The "enabled" property prints a '1' if the TPM chip is enabled,
 		meaning that it should be visible to the OS. This property
 		may be visible but produce a '0' after some operation that
@@ -78,7 +78,7 @@ Description:	The "enabled" property prints a '1' if the TPM chip is enabled,
 What:		/sys/class/tpm/tpmX/device/owned
 Date:		April 2006
 KernelVersion:	2.6.17
-Contact:	linux-integrity@vger.kernel.org
+Contact:	tpmdd-devel@lists.sf.net
 Description:	The "owned" property produces a '1' if the TPM_TakeOwnership
 		ordinal has been executed successfully in the chip. A '0'
 		indicates that ownership hasn't been taken.
@@ -86,7 +86,7 @@ Description:	The "owned" property produces a '1' if the TPM_TakeOwnership
 What:		/sys/class/tpm/tpmX/device/pcrs
 Date:		April 2005
 KernelVersion:	2.6.12
-Contact:	linux-integrity@vger.kernel.org
+Contact:	tpmdd-devel@lists.sf.net
 Description:	The "pcrs" property will dump the current value of all Platform
 		Configuration Registers in the TPM. Note that since these
 		values may be constantly changing, the output is only valid
@@ -109,7 +109,7 @@ Description:	The "pcrs" property will dump the current value of all Platform
 What:		/sys/class/tpm/tpmX/device/pubek
 Date:		April 2005
 KernelVersion:	2.6.12
-Contact:	linux-integrity@vger.kernel.org
+Contact:	tpmdd-devel@lists.sf.net
 Description:	The "pubek" property will return the TPM's public endorsement
 		key if possible. If the TPM has had ownership established and
 		is version 1.2, the pubek will not be available without the
@@ -161,7 +161,7 @@ Description:	The "pubek" property will return the TPM's public endorsement
 What:		/sys/class/tpm/tpmX/device/temp_deactivated
 Date:		April 2006
 KernelVersion:	2.6.17
-Contact:	linux-integrity@vger.kernel.org
+Contact:	tpmdd-devel@lists.sf.net
 Description:	The "temp_deactivated" property returns a '1' if the chip has
 		been temporarily deactivated, usually until the next power
 		cycle. Whether a warm boot (reboot) will clear a TPM chip
@@ -170,7 +170,7 @@ Description:	The "temp_deactivated" property returns a '1' if the chip has
 What:		/sys/class/tpm/tpmX/device/timeouts
 Date:		March 2011
 KernelVersion:	3.1
-Contact:	linux-integrity@vger.kernel.org
+Contact:	tpmdd-devel@lists.sf.net
 Description:	The "timeouts" property shows the 4 vendor-specific values
 		for the TPM's interface spec timeouts. The use of these
 		timeouts is defined by the TPM interface spec that the chip
@@ -183,14 +183,3 @@ Description:	The "timeouts" property shows the 4 vendor-specific values
 		The four timeout values are shown in usecs, with a trailing
 		"[original]" or "[adjusted]" depending on whether the values
 		were scaled by the driver to be reported in usec from msecs.
-
-What:		/sys/class/tpm/tpmX/tpm_version_major
-Date:		October 2019
-KernelVersion:	5.5
-Contact:	linux-integrity@vger.kernel.org
-Description:	The "tpm_version_major" property shows the TCG spec major version
-		implemented by the TPM device.
-
-		Example output:
-
-		2

Documentation/ABI/stable/sysfs-driver-aspeed-vuart

@@ -6,19 +6,10 @@ Description:	Configures which IO port the host side of the UART
 Users:		OpenBMC.  Proposed changes should be mailed to
 		openbmc@lists.ozlabs.org
 
-What:		/sys/bus/platform/drivers/aspeed-vuart/*/sirq
+What:		/sys/bus/platform/drivers/aspeed-vuart*/sirq
 Date:		April 2017
 Contact:	Jeremy Kerr <jk@ozlabs.org>
 Description:	Configures which interrupt number the host side of
 		the UART will appear on the host <-> BMC LPC bus.
 Users:		OpenBMC.  Proposed changes should be mailed to
 		openbmc@lists.ozlabs.org
-
-What:		/sys/bus/platform/drivers/aspeed-vuart/*/sirq_polarity
-Date:		July 2019
-Contact:	Oskar Senft <osk@google.com>
-Description:	Configures the polarity of the serial interrupt to the
-		host via the BMC LPC bus.
-		Set to 0 for active-low or 1 for active-high.
-Users:		OpenBMC.  Proposed changes should be mailed to
-		openbmc@lists.ozlabs.org

Documentation/ABI/stable/sysfs-driver-dma-idxd

@@ -1,171 +0,0 @@
-What:           sys/bus/dsa/devices/dsa<m>/cdev_major
-Date:           Oct 25, 2019
-KernelVersion: 	5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:	The major number that the character device driver assigned to
-		this device.
-
-What:           sys/bus/dsa/devices/dsa<m>/errors
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The error information for this device.
-
-What:           sys/bus/dsa/devices/dsa<m>/max_batch_size
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The largest number of work descriptors in a batch.
-
-What:           sys/bus/dsa/devices/dsa<m>/max_work_queues_size
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The maximum work queue size supported by this device.
-
-What:           sys/bus/dsa/devices/dsa<m>/max_engines
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The maximum number of engines supported by this device.
-
-What:           sys/bus/dsa/devices/dsa<m>/max_groups
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The maximum number of groups can be created under this device.
-
-What:           sys/bus/dsa/devices/dsa<m>/max_tokens
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The total number of bandwidth tokens supported by this device.
-		The bandwidth tokens represent resources within the DSA
-		implementation, and these resources are allocated by engines to
-		support operations.
-
-What:           sys/bus/dsa/devices/dsa<m>/max_transfer_size
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The number of bytes to be read from the source address to
-		perform the operation. The maximum transfer size is dependent on
-		the workqueue the descriptor was submitted to.
-
-What:           sys/bus/dsa/devices/dsa<m>/max_work_queues
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The maximum work queue number that this device supports.
-
-What:           sys/bus/dsa/devices/dsa<m>/numa_node
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The numa node number for this device.
-
-What:           sys/bus/dsa/devices/dsa<m>/op_cap
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The operation capability bit mask specify the operation types
-		supported by the this device.
-
-What:           sys/bus/dsa/devices/dsa<m>/state
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The state information of this device. It can be either enabled
-		or disabled.
-
-What:           sys/bus/dsa/devices/dsa<m>/group<m>.<n>
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The assigned group under this device.
-
-What:           sys/bus/dsa/devices/dsa<m>/engine<m>.<n>
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The assigned engine under this device.
-
-What:           sys/bus/dsa/devices/dsa<m>/wq<m>.<n>
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The assigned work queue under this device.
-
-What:           sys/bus/dsa/devices/dsa<m>/configurable
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    To indicate if this device is configurable or not.
-
-What:           sys/bus/dsa/devices/dsa<m>/token_limit
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The maximum number of bandwidth tokens that may be in use at
-		one time by operations that access low bandwidth memory in the
-		device.
-
-What:           sys/bus/dsa/devices/wq<m>.<n>/group_id
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The group id that this work queue belongs to.
-
-What:           sys/bus/dsa/devices/wq<m>.<n>/size
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The work queue size for this work queue.
-
-What:           sys/bus/dsa/devices/wq<m>.<n>/type
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The type of this work queue, it can be "kernel" type for work
-		queue usages in the kernel space or "user" type for work queue
-		usages by applications in user space.
-
-What:           sys/bus/dsa/devices/wq<m>.<n>/cdev_minor
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The minor number assigned to this work queue by the character
-		device driver.
-
-What:           sys/bus/dsa/devices/wq<m>.<n>/mode
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The work queue mode type for this work queue.
-
-What:           sys/bus/dsa/devices/wq<m>.<n>/priority
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The priority value of this work queue, it is a vlue relative to
-		other work queue in the same group to control quality of service
-		for dispatching work from multiple workqueues in the same group.
-
-What:           sys/bus/dsa/devices/wq<m>.<n>/state
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The current state of the work queue.
-
-What:           sys/bus/dsa/devices/wq<m>.<n>/threshold
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The number of entries in this work queue that may be filled
-		via a limited portal.
-
-What:           sys/bus/dsa/devices/engine<m>.<n>/group_id
-Date:           Oct 25, 2019
-KernelVersion:  5.6.0
-Contact:        dmaengine@vger.kernel.org
-Description:    The group that this engine belongs to.

Documentation/ABI/stable/sysfs-driver-ib_srp

@@ -67,8 +67,6 @@ Description:	Interface for making ib_srp connect to a new target.
 		  initiator is allowed to queue per SCSI host. The default
 		  value for this parameter is 62. The lowest supported value
 		  is 2.
-		* max_it_iu_size, a decimal number specifying the maximum
-		  initiator to target information unit length.
 
 What:		/sys/class/infiniband_srp/srp-<hca>-<port_number>/ibdev
 Date:		January 2, 2006

Documentation/ABI/stable/sysfs-driver-mlxreg-io

@@ -1,4 +1,5 @@
 What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/asic_health
+
 Date:		June 2018
 KernelVersion:	4.19
 Contact:	Vadim Pasternak <vadimpmellanox.com>
@@ -18,6 +19,7 @@ Description:	These files show with which CPLD versions have been burned
 		The files are read only.
 
 What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/fan_dir
+
 Date:		December 2018
 KernelVersion:	5.0
 Contact:	Vadim Pasternak <vadimpmellanox.com>
@@ -27,16 +29,18 @@ Description:	This file shows the system fans direction:
 
 		The files are read only.
 
-What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld3_version
+What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_enable
+
 Date:		November 2018
 KernelVersion:	5.0
 Contact:	Vadim Pasternak <vadimpmellanox.com>
 Description:	These files show with which CPLD versions have been burned
-		on LED or Gearbox board.
+		on LED board.
 
 		The files are read only.
 
 What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_enable
+
 Date:		November 2018
 KernelVersion:	5.0
 Contact:	Vadim Pasternak <vadimpmellanox.com>
@@ -104,6 +108,7 @@ What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_pwr_fail
 What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_from_comex
 What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_system
 What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_voltmon_upgrade_fail
+
 Date:		November 2018
 KernelVersion:	5.0
 Contact:	Vadim Pasternak <vadimpmellanox.com>
@@ -116,21 +121,6 @@ Description:	These files show the system reset cause, as following: ComEx
 
 		The files are read only.
 
-What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld4_version
-Date:		November 2018
-KernelVersion:	5.0
-Contact:	Vadim Pasternak <vadimpmellanox.com>
-Description:	These files show with which CPLD versions have been burned
-		on LED board.
-
-		The files are read only.
-
-What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_thermal
-What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_wd
-What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_from_asic
-What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_reload_bios
-What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_sff_wd
-What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_swb_wd
 Date:		June 2019
 KernelVersion:	5.3
 Contact:	Vadim Pasternak <vadimpmellanox.com>
@@ -144,65 +134,9 @@ Description:	These files show the system reset cause, as following:
 
 		The files are read only.
 
-What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/config1
-What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/config2
-Date:		January 2020
-KernelVersion:	5.6
-Contact:	Vadim Pasternak <vadimpmellanox.com>
-Description:	These files show system static topology identification
-		like system's static I2C topology, number and type of FPGA
-		devices within the system and so on.
-
-		The files are read only.
-
-What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_ac_pwr_fail
-What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_platform
-What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_soc
-What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_sw_pwr_off
-Date:		January 2020
-KernelVersion:	5.6
-Contact:	Vadim Pasternak <vadimpmellanox.com>
-Description:	These files show the system reset causes, as following: reset
-		due to AC power failure, reset invoked from software by
-		assertion reset signal through CPLD. reset caused by signal
-		asserted by SOC through ACPI register, reset invoked from
-		software by assertion power off signal through CPLD.
-
-		The files are read only.
-
-What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/pcie_asic_reset_dis
-Date:		January 2020
-KernelVersion:	5.6
-Contact:	Vadim Pasternak <vadimpmellanox.com>
-Description:	This file allows to retain ASIC up during PCIe root complex
-		reset, when attribute is set 1.
-
-		The file is read/write.
-
-What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/vpd_wp
-Date:		January 2020
-KernelVersion:	5.6
-Contact:	Vadim Pasternak <vadimpmellanox.com>
-Description:	This file allows to overwrite system VPD hardware wrtie
-		protection when attribute is set 1.
-
-		The file is read/write.
-
-What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/voltreg_update_status
-Date:		January 2020
-KernelVersion:	5.6
-Contact:	Vadim Pasternak <vadimpmellanox.com>
-Description:	This file exposes the configuration update status of burnable
-		voltage regulator devices. The status values are as following:
-		0 - OK; 1 - CRC failure; 2 = I2C failure; 3 - in progress.
-
-		The file is read only.
-
-What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/ufm_version
-Date:		January 2020
-KernelVersion:	5.6
-Contact:	Vadim Pasternak <vadimpmellanox.com>
-Description:	This file exposes the firmware version of burnable voltage
-		regulator devices.
-
-		The file is read only.
+What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_thermal
+What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_wd
+What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_from_asic
+What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_reload_bios
+What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_sff_wd
+What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_swb_wd

Documentation/ABI/stable/sysfs-driver-w1_ds28e04

@@ -2,7 +2,7 @@ What:		/sys/bus/w1/devices/.../pio
 Date:		May 2012
 Contact:	Markus Franke <franm@hrz.tu-chemnitz.de>
 Description:	read/write the contents of the two PIO's of the DS28E04-100
-		see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
+		see Documentation/w1/slaves/w1_ds28e04 for detailed information
 Users:		any user space application which wants to communicate with DS28E04-100
 
 
@@ -11,5 +11,5 @@ What:		/sys/bus/w1/devices/.../eeprom
 Date:		May 2012
 Contact:	Markus Franke <franm@hrz.tu-chemnitz.de>
 Description:	read/write the contents of the EEPROM memory of the DS28E04-100
-		see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
+		see Documentation/w1/slaves/w1_ds28e04 for detailed information
 Users:		any user space application which wants to communicate with DS28E04-100

Documentation/ABI/stable/sysfs-driver-w1_ds28ea00

@@ -2,5 +2,5 @@ What:		/sys/bus/w1/devices/.../w1_seq
 Date:		Apr 2015
 Contact:	Matt Campbell <mattrcampbell@gmail.com>
 Description:	Support for the DS28EA00 chain sequence function
-		see Documentation/w1/slaves/w1_therm.rst for detailed information
+		see Documentation/w1/slaves/w1_therm for detailed information
 Users:		any user space application which wants to communicate with DS28EA00

Documentation/ABI/testing/configfs-usb-gadget

@@ -16,10 +16,6 @@ Description:
 				write UDC's name found in /sys/class/udc/*
 				to bind a gadget, empty string "" to unbind.
 
-		max_speed	- maximum speed the driver supports. Valid
-				names are super-speed-plus, super-speed,
-				high-speed, full-speed, and low-speed.
-
 		bDeviceClass	- USB device class code
 		bDeviceSubClass	- USB device subclass code
 		bDeviceProtocol	- USB device protocol code

Documentation/ABI/testing/debugfs-hisi-hpre

@@ -1,57 +0,0 @@
-What:           /sys/kernel/debug/hisi_hpre/<bdf>/cluster[0-3]/regs
-Date:           Sep 2019
-Contact:        linux-crypto@vger.kernel.org
-Description:    Dump debug registers from the HPRE cluster.
-		Only available for PF.
-
-What:           /sys/kernel/debug/hisi_hpre/<bdf>/cluster[0-3]/cluster_ctrl
-Date:           Sep 2019
-Contact:        linux-crypto@vger.kernel.org
-Description:    Write the HPRE core selection in the cluster into this file,
-		and then we can read the debug information of the core.
-		Only available for PF.
-
-What:           /sys/kernel/debug/hisi_hpre/<bdf>/rdclr_en
-Date:           Sep 2019
-Contact:        linux-crypto@vger.kernel.org
-Description:    HPRE cores debug registers read clear control. 1 means enable
-		register read clear, otherwise 0. Writing to this file has no
-		functional effect, only enable or disable counters clear after
-		reading of these registers.
-		Only available for PF.
-
-What:           /sys/kernel/debug/hisi_hpre/<bdf>/current_qm
-Date:           Sep 2019
-Contact:        linux-crypto@vger.kernel.org
-Description:    One HPRE controller has one PF and multiple VFs, each function
-		has a QM. Select the QM which below qm refers to.
-		Only available for PF.
-
-What:           /sys/kernel/debug/hisi_hpre/<bdf>/regs
-Date:           Sep 2019
-Contact:        linux-crypto@vger.kernel.org
-Description:    Dump debug registers from the HPRE.
-		Only available for PF.
-
-What:           /sys/kernel/debug/hisi_hpre/<bdf>/qm/qm_regs
-Date:           Sep 2019
-Contact:        linux-crypto@vger.kernel.org
-Description:    Dump debug registers from the QM.
-		Available for PF and VF in host. VF in guest currently only
-		has one debug register.
-
-What:           /sys/kernel/debug/hisi_hpre/<bdf>/qm/current_q
-Date:           Sep 2019
-Contact:        linux-crypto@vger.kernel.org
-Description:    One QM may contain multiple queues. Select specific queue to
-		show its debug registers in above qm_regs.
-		Only available for PF.
-
-What:           /sys/kernel/debug/hisi_hpre/<bdf>/qm/clear_enable
-Date:           Sep 2019
-Contact:        linux-crypto@vger.kernel.org
-Description:    QM debug registers(qm_regs) read clear control. 1 means enable
-		register read clear, otherwise 0.
-		Writing to this file has no functional effect, only enable or
-		disable counters clear after reading of these registers.
-		Only available for PF.

Documentation/ABI/testing/debugfs-hisi-sec

@@ -1,43 +0,0 @@
-What:           /sys/kernel/debug/hisi_sec/<bdf>/sec_dfx
-Date:           Oct 2019
-Contact:        linux-crypto@vger.kernel.org
-Description:    Dump the debug registers of SEC cores.
-		Only available for PF.
-
-What:           /sys/kernel/debug/hisi_sec/<bdf>/clear_enable
-Date:           Oct 2019
-Contact:        linux-crypto@vger.kernel.org
-Description:    Enabling/disabling of clear action after reading
-		the SEC debug registers.
-		0: disable, 1: enable.
-		Only available for PF, and take no other effect on SEC.
-
-What:           /sys/kernel/debug/hisi_sec/<bdf>/current_qm
-Date:           Oct 2019
-Contact:        linux-crypto@vger.kernel.org
-Description:    One SEC controller has one PF and multiple VFs, each function
-		has a QM. This file can be used to select the QM which below
-		qm refers to.
-		Only available for PF.
-
-What:           /sys/kernel/debug/hisi_sec/<bdf>/qm/qm_regs
-Date:           Oct 2019
-Contact:        linux-crypto@vger.kernel.org
-Description:    Dump of QM related debug registers.
-		Available for PF and VF in host. VF in guest currently only
-		has one debug register.
-
-What:           /sys/kernel/debug/hisi_sec/<bdf>/qm/current_q
-Date:           Oct 2019
-Contact:        linux-crypto@vger.kernel.org
-Description:    One QM of SEC may contain multiple queues. Select specific
-		queue to show its debug registers in above 'qm_regs'.
-		Only available for PF.
-
-What:           /sys/kernel/debug/hisi_sec/<bdf>/qm/clear_enable
-Date:           Oct 2019
-Contact:        linux-crypto@vger.kernel.org
-Description:    Enabling/disabling of clear action after reading
-		the SEC's QM debug registers.
-		0: disable, 1: enable.
-		Only available for PF, and take no other effect on SEC.

Documentation/ABI/testing/debugfs-hisi-zip

@@ -1,50 +0,0 @@
-What:           /sys/kernel/debug/hisi_zip/<bdf>/comp_core[01]/regs
-Date:           Nov 2018
-Contact:        linux-crypto@vger.kernel.org
-Description:    Dump of compression cores related debug registers.
-		Only available for PF.
-
-What:           /sys/kernel/debug/hisi_zip/<bdf>/decomp_core[0-5]/regs
-Date:           Nov 2018
-Contact:        linux-crypto@vger.kernel.org
-Description:    Dump of decompression cores related debug registers.
-		Only available for PF.
-
-What:           /sys/kernel/debug/hisi_zip/<bdf>/clear_enable
-Date:           Nov 2018
-Contact:        linux-crypto@vger.kernel.org
-Description:    Compression/decompression core debug registers read clear
-		control. 1 means enable register read clear, otherwise 0.
-		Writing to this file has no functional effect, only enable or
-		disable counters clear after reading of these registers.
-		Only available for PF.
-
-What:           /sys/kernel/debug/hisi_zip/<bdf>/current_qm
-Date:           Nov 2018
-Contact:        linux-crypto@vger.kernel.org
-Description:    One ZIP controller has one PF and multiple VFs, each function
-		has a QM. Select the QM which below qm refers to.
-		Only available for PF.
-
-What:           /sys/kernel/debug/hisi_zip/<bdf>/qm/qm_regs
-Date:           Nov 2018
-Contact:        linux-crypto@vger.kernel.org
-Description:    Dump of QM related debug registers.
-		Available for PF and VF in host. VF in guest currently only
-		has one debug register.
-
-What:           /sys/kernel/debug/hisi_zip/<bdf>/qm/current_q
-Date:           Nov 2018
-Contact:        linux-crypto@vger.kernel.org
-Description:    One QM may contain multiple queues. Select specific queue to
-		show its debug registers in above qm_regs.
-		Only available for PF.
-
-What:           /sys/kernel/debug/hisi_zip/<bdf>/qm/clear_enable
-Date:           Nov 2018
-Contact:        linux-crypto@vger.kernel.org
-Description:    QM debug registers(qm_regs) read clear control. 1 means enable
-		register read clear, otherwise 0.
-		Writing to this file has no functional effect, only enable or
-		disable counters clear after reading of these registers.
-		Only available for PF.

Documentation/ABI/testing/debugfs-hyperv

@@ -1,23 +0,0 @@
-What:           /sys/kernel/debug/hyperv/<UUID>/fuzz_test_state
-Date:           October 2019
-KernelVersion:  5.5
-Contact:        Branden Bonaby <brandonbonaby94@gmail.com>
-Description:    Fuzz testing status of a vmbus device, whether its in an ON
-                state or a OFF state
-Users:          Debugging tools
-
-What:           /sys/kernel/debug/hyperv/<UUID>/delay/fuzz_test_buffer_interrupt_delay
-Date:           October 2019
-KernelVersion:  5.5
-Contact:        Branden Bonaby <brandonbonaby94@gmail.com>
-Description:    Fuzz testing buffer interrupt delay value between 0 - 1000
-		 microseconds (inclusive).
-Users:          Debugging tools
-
-What:           /sys/kernel/debug/hyperv/<UUID>/delay/fuzz_test_message_delay
-Date:           October 2019
-KernelVersion:  5.5
-Contact:        Branden Bonaby <brandonbonaby94@gmail.com>
-Description:    Fuzz testing message delay value between 0 - 1000 microseconds
-		 (inclusive).
-Users:          Debugging tools

Documentation/ABI/testing/debugfs-moxtet

@@ -1,23 +0,0 @@
-What:		/sys/kernel/debug/moxtet/input
-Date:		March 2019
-KernelVersion:	5.3
-Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(R) Read input from the shift registers, in hexadecimal.
-		Returns N+1 bytes, where N is the number of Moxtet connected
-		modules. The first byte is from the CPU board itself.
-		Example: 101214
-			 10: CPU board with SD card
-			 12: 2 = PCIe module, 1 = IRQ not active
-			 14: 4 = Peridot module, 1 = IRQ not active
-
-What:		/sys/kernel/debug/moxtet/output
-Date:		March 2019
-KernelVersion:	5.3
-Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(RW) Read last written value to the shift registers, in
-		hexadecimal, or write values to the shift registers, also
-		in hexadecimal.
-		Example: 0102
-			 01: 01 was last written, or is to be written, to the
-			     first module's shift register
-			 02: the same for second module

Documentation/ABI/testing/dev-kmsg

@@ -12,7 +12,7 @@ Description:	The /dev/kmsg character device node provides userspace access
 		The logged line can be prefixed with a <N> syslog prefix, which
 		carries the syslog priority and facility. The single decimal
 		prefix number is composed of the 3 lowest bits being the syslog
-		priority and the next 8 bits the syslog facility number.
+		priority and the higher bits the syslog facility number.
 
 		If no prefix is given, the priority number is the default kernel
 		log priority and the facility number is set to LOG_USER (1). It
@@ -90,12 +90,13 @@ Description:	The /dev/kmsg character device node provides userspace access
 		  +sound:card0 - subsystem:devname
 
 		The flags field carries '-' by default. A 'c' indicates a
-		fragment of a line. Note, that these hints about continuation
-		lines are not necessarily correct, and the stream could be
-		interleaved with unrelated messages, but merging the lines in
-		the output usually produces better human readable results. A
-		similar logic is used internally when messages are printed to
-		the console, /proc/kmsg or the syslog() syscall.
+		fragment of a line. All following fragments are flagged with
+		'+'. Note, that these hints about continuation lines are not
+		necessarily correct, and the stream could be interleaved with
+		unrelated messages, but merging the lines in the output
+		usually produces better human readable results. A similar
+		logic is used internally when messages are printed to the
+		console, /proc/kmsg or the syslog() syscall.
 
 		By default, kernel tries to avoid fragments by concatenating
 		when it can and fragments are rare; however, when extended

Documentation/ABI/testing/ima_policy

@@ -25,11 +25,10 @@ Description:
 			lsm:	[[subj_user=] [subj_role=] [subj_type=]
 				 [obj_user=] [obj_role=] [obj_type=]]
 			option:	[[appraise_type=]] [template=] [permit_directio]
-				[appraise_flag=] [keyrings=]
 		base: 	func:= [BPRM_CHECK][MMAP_CHECK][CREDS_CHECK][FILE_CHECK][MODULE_CHECK]
 				[FIRMWARE_CHECK]
 				[KEXEC_KERNEL_CHECK] [KEXEC_INITRAMFS_CHECK]
-				[KEXEC_CMDLINE] [KEY_CHECK]
+				[KEXEC_CMDLINE]
 			mask:= [[^]MAY_READ] [[^]MAY_WRITE] [[^]MAY_APPEND]
 			       [[^]MAY_EXEC]
 			fsmagic:= hex value
@@ -38,13 +37,7 @@ Description:
 			euid:= decimal value
 			fowner:= decimal value
 		lsm:  	are LSM specific
-		option:	appraise_type:= [imasig] [imasig|modsig]
-			appraise_flag:= [check_blacklist]
-			Currently, blacklist check is only for files signed with appended
-			signature.
-			keyrings:= list of keyrings
-			(eg, .builtin_trusted_keys|.ima). Only valid
-			when action is "measure" and func is KEY_CHECK.
+		option:	appraise_type:= [imasig]
 			template:= name of a defined IMA template type
 			(eg, ima-ng). Only valid when action is "measure".
 			pcr:= decimal value
@@ -112,16 +105,3 @@ Description:
 
 			measure func=KEXEC_KERNEL_CHECK pcr=4
 			measure func=KEXEC_INITRAMFS_CHECK pcr=5
-
-		Example of appraise rule allowing modsig appended signatures:
-
-			appraise func=KEXEC_KERNEL_CHECK appraise_type=imasig|modsig
-
-		Example of measure rule using KEY_CHECK to measure all keys:
-
-			measure func=KEY_CHECK
-
-		Example of measure rule using KEY_CHECK to only measure
-		keys added to .builtin_trusted_keys or .ima keyring:
-
-			measure func=KEY_CHECK keyrings=.builtin_trusted_keys|.ima

Documentation/ABI/testing/procfs-diskstats

@@ -29,9 +29,4 @@ Description:
 		17 - sectors discarded
 		18 - time spent discarding
 
-		Kernel 5.5+ appends two more fields for flush requests:
-
-		19 - flush requests completed successfully
-		20 - time spent flushing
-
 		For more details refer to Documentation/admin-guide/iostats.rst

Documentation/ABI/testing/rtc-cdev

@@ -33,14 +33,6 @@ Description:
 		  Requires a separate RTC_PIE_ON call to enable the periodic
 		  interrupts.
 
-		* RTC_VL_READ: Read the voltage inputs status of the RTC when
-		  supported. The value is a bit field of RTC_VL_*, giving the
-		  status of the main and backup voltages.
-
-		* RTC_VL_CLEAR: Clear the voltage status of the RTC. Some RTCs
-		  need user interaction when the backup power provider is
-		  replaced or charged to be able to clear the status.
-
 		The ioctl() calls supported by the older /dev/rtc interface are
 		also supported by the newer RTC class framework. However,
 		because the chips and systems are not standardized, some PC/AT

Documentation/ABI/testing/sysfs-block

@@ -15,12 +15,6 @@ Description:
 		 9 - I/Os currently in progress
 		10 - time spent doing I/Os (ms)
 		11 - weighted time spent doing I/Os (ms)
-		12 - discards completed
-		13 - discards merged
-		14 - sectors discarded
-		15 - time spent discarding (ms)
-		16 - flush requests completed
-		17 - time spent flushing (ms)
 		For more details refer Documentation/admin-guide/iostats.rst
 
 

Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x

@@ -1,4 +1,4 @@
-What:		/sys/bus/coresight/devices/etm<N>/enable_source
+What:		/sys/bus/coresight/devices/<memory_map>.etm/enable_source
 Date:		April 2015
 KernelVersion:  4.01
 Contact:        Mathieu Poirier <mathieu.poirier@linaro.org>
@@ -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<N>/cpu
+What:		/sys/bus/coresight/devices/<memory_map>.etm/cpu
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description:	(R) The CPU this tracing entity is associated with.
 
-What:		/sys/bus/coresight/devices/etm<N>/nr_pe_cmp
+What:		/sys/bus/coresight/devices/<memory_map>.etm/nr_pe_cmp
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description:	(R) Indicates the number of PE comparator inputs that are
 		available for tracing.
 
-What:		/sys/bus/coresight/devices/etm<N>/nr_addr_cmp
+What:		/sys/bus/coresight/devices/<memory_map>.etm/nr_addr_cmp
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description:	(R) Indicates the number of address comparator pairs that are
 		available for tracing.
 
-What:		/sys/bus/coresight/devices/etm<N>/nr_cntr
+What:		/sys/bus/coresight/devices/<memory_map>.etm/nr_cntr
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description:	(R) Indicates the number of counters that are available for
 		tracing.
 
-What:		/sys/bus/coresight/devices/etm<N>/nr_ext_inp
+What:		/sys/bus/coresight/devices/<memory_map>.etm/nr_ext_inp
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description:	(R) Indicates how many external inputs are implemented.
 
-What:		/sys/bus/coresight/devices/etm<N>/numcidc
+What:		/sys/bus/coresight/devices/<memory_map>.etm/numcidc
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description:	(R) Indicates the number of Context ID comparators that are
 		available for tracing.
 
-What:		/sys/bus/coresight/devices/etm<N>/numvmidc
+What:		/sys/bus/coresight/devices/<memory_map>.etm/numvmidc
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description:	(R) Indicates the number of VMID comparators that are available
 		for tracing.
 
-What:		/sys/bus/coresight/devices/etm<N>/nrseqstate
+What:		/sys/bus/coresight/devices/<memory_map>.etm/nrseqstate
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description:	(R) Indicates the number of sequencer states that are
 		implemented.
 
-What:		/sys/bus/coresight/devices/etm<N>/nr_resource
+What:		/sys/bus/coresight/devices/<memory_map>.etm/nr_resource
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description:	(R) Indicates the number of resource selection pairs that are
 		available for tracing.
 
-What:		/sys/bus/coresight/devices/etm<N>/nr_ss_cmp
+What:		/sys/bus/coresight/devices/<memory_map>.etm/nr_ss_cmp
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description:	(R) Indicates the number of single-shot comparator controls that
 		are available for tracing.
 
-What:		/sys/bus/coresight/devices/etm<N>/reset
+What:		/sys/bus/coresight/devices/<memory_map>.etm/reset
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(W) Cancels all configuration on a trace unit and set it back
 		to its boot configuration.
 
-What:		/sys/bus/coresight/devices/etm<N>/mode
+What:		/sys/bus/coresight/devices/<memory_map>.etm/mode
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
@@ -91,349 +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<N>/pe
+What:		/sys/bus/coresight/devices/<memory_map>.etm/pe
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Controls which PE to trace.
 
-What:		/sys/bus/coresight/devices/etm<N>/event
+What:		/sys/bus/coresight/devices/<memory_map>.etm/event
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Controls the tracing of arbitrary events from bank 0 to 3.
 
-What:		/sys/bus/coresight/devices/etm<N>/event_instren
+What:		/sys/bus/coresight/devices/<memory_map>.etm/event_instren
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Controls the behavior of the events in bank 0 to 3.
 
-What:		/sys/bus/coresight/devices/etm<N>/event_ts
+What:		/sys/bus/coresight/devices/<memory_map>.etm/event_ts
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Controls the insertion of global timestamps in the trace
 		streams.
 
-What:		/sys/bus/coresight/devices/etm<N>/syncfreq
+What:		/sys/bus/coresight/devices/<memory_map>.etm/syncfreq
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Controls how often trace synchronization requests occur.
 
-What:		/sys/bus/coresight/devices/etm<N>/cyc_threshold
+What:		/sys/bus/coresight/devices/<memory_map>.etm/cyc_threshold
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Sets the threshold value for cycle counting.
 
-What:		/sys/bus/coresight/devices/etm<N>/bb_ctrl
+What:		/sys/bus/coresight/devices/<memory_map>.etm/bb_ctrl
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Controls which regions in the memory map are enabled to
 		use branch broadcasting.
 
-What:		/sys/bus/coresight/devices/etm<N>/event_vinst
+What:		/sys/bus/coresight/devices/<memory_map>.etm/event_vinst
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Controls instruction trace filtering.
 
-What:		/sys/bus/coresight/devices/etm<N>/s_exlevel_vinst
+What:		/sys/bus/coresight/devices/<memory_map>.etm/s_exlevel_vinst
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) In Secure state, each bit controls whether instruction
 		tracing is enabled for the corresponding exception level.
 
-What:		/sys/bus/coresight/devices/etm<N>/ns_exlevel_vinst
+What:		/sys/bus/coresight/devices/<memory_map>.etm/ns_exlevel_vinst
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 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<N>/addr_idx
+What:		/sys/bus/coresight/devices/<memory_map>.etm/addr_idx
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Select which address comparator or pair (of comparators) to
 		work with.
 
-What:		/sys/bus/coresight/devices/etm<N>/addr_instdatatype
+What:		/sys/bus/coresight/devices/<memory_map>.etm/addr_instdatatype
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Controls what type of comparison the trace unit performs.
 
-What:		/sys/bus/coresight/devices/etm<N>/addr_single
+What:		/sys/bus/coresight/devices/<memory_map>.etm/addr_single
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Used to setup single address comparator values.
 
-What:		/sys/bus/coresight/devices/etm<N>/addr_range
+What:		/sys/bus/coresight/devices/<memory_map>.etm/addr_range
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Used to setup address range comparator values.
 
-What:		/sys/bus/coresight/devices/etm<N>/seq_idx
+What:		/sys/bus/coresight/devices/<memory_map>.etm/seq_idx
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Select which sequensor.
 
-What:		/sys/bus/coresight/devices/etm<N>/seq_state
+What:		/sys/bus/coresight/devices/<memory_map>.etm/seq_state
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Use this to set, or read, the sequencer state.
 
-What:		/sys/bus/coresight/devices/etm<N>/seq_event
+What:		/sys/bus/coresight/devices/<memory_map>.etm/seq_event
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Moves the sequencer state to a specific state.
 
-What:		/sys/bus/coresight/devices/etm<N>/seq_reset_event
+What:		/sys/bus/coresight/devices/<memory_map>.etm/seq_reset_event
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Moves the sequencer to state 0 when a programmed event
 		occurs.
 
-What:		/sys/bus/coresight/devices/etm<N>/cntr_idx
+What:		/sys/bus/coresight/devices/<memory_map>.etm/cntr_idx
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Select which counter unit to work with.
 
-What:		/sys/bus/coresight/devices/etm<N>/cntrldvr
+What:		/sys/bus/coresight/devices/<memory_map>.etm/cntrldvr
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) This sets or returns the reload count value of the
 		specific counter.
 
-What:		/sys/bus/coresight/devices/etm<N>/cntr_val
+What:		/sys/bus/coresight/devices/<memory_map>.etm/cntr_val
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) This sets or returns the current count value of the
                 specific counter.
 
-What:		/sys/bus/coresight/devices/etm<N>/cntr_ctrl
+What:		/sys/bus/coresight/devices/<memory_map>.etm/cntr_ctrl
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Controls the operation of the selected counter.
 
-What:		/sys/bus/coresight/devices/etm<N>/res_idx
+What:		/sys/bus/coresight/devices/<memory_map>.etm/res_idx
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Select which resource selection unit to work with.
 
-What:		/sys/bus/coresight/devices/etm<N>/res_ctrl
+What:		/sys/bus/coresight/devices/<memory_map>.etm/res_ctrl
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description: 	(RW) Controls the selection of the resources in the trace unit.
 
-What:		/sys/bus/coresight/devices/etm<N>/ctxid_idx
+What:		/sys/bus/coresight/devices/<memory_map>.etm/ctxid_idx
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description:	(RW) Select which context ID comparator to work with.
 
-What:		/sys/bus/coresight/devices/etm<N>/ctxid_pid
+What:		/sys/bus/coresight/devices/<memory_map>.etm/ctxid_pid
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description:	(RW) Get/Set the context ID comparator value to trigger on.
 
-What:		/sys/bus/coresight/devices/etm<N>/ctxid_masks
+What:		/sys/bus/coresight/devices/<memory_map>.etm/ctxid_masks
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description:	(RW) Mask for all 8 context ID comparator value
 		registers (if implemented).
 
-What:		/sys/bus/coresight/devices/etm<N>/vmid_idx
+What:		/sys/bus/coresight/devices/<memory_map>.etm/vmid_idx
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description:	(RW) Select which virtual machine ID comparator to work with.
 
-What:		/sys/bus/coresight/devices/etm<N>/vmid_val
+What:		/sys/bus/coresight/devices/<memory_map>.etm/vmid_val
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description:	(RW) Get/Set the virtual machine ID comparator value to
 		trigger on.
 
-What:		/sys/bus/coresight/devices/etm<N>/vmid_masks
+What:		/sys/bus/coresight/devices/<memory_map>.etm/vmid_masks
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description:	(RW) Mask for all 8 virtual machine ID comparator value
 		registers (if implemented).
 
-What:		/sys/bus/coresight/devices/etm<N>/addr_exlevel_s_ns
-Date:		December 2019
-KernelVersion:	5.5
-Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(RW) Set the Exception Level matching bits for secure and
-		non-secure exception levels.
-
-What:		/sys/bus/coresight/devices/etm<N>/vinst_pe_cmp_start_stop
-Date:		December 2019
-KernelVersion:	5.5
-Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(RW) Access the start stop control register for PE input
-		comparators.
-
-What:		/sys/bus/coresight/devices/etm<N>/addr_cmp_view
-Date:		December 2019
-KernelVersion:	5.5
-Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Print the current settings for the selected address
-		comparator.
-
-What:		/sys/bus/coresight/devices/etm<N>/sshot_idx
-Date:		December 2019
-KernelVersion:	5.5
-Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(RW) Select the single shot control register to access.
-
-What:		/sys/bus/coresight/devices/etm<N>/sshot_ctrl
-Date:		December 2019
-KernelVersion:	5.5
-Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(RW) Access the selected single shot control register.
-
-What:		/sys/bus/coresight/devices/etm<N>/sshot_status
-Date:		December 2019
-KernelVersion:	5.5
-Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Print the current value of the selected single shot
-		status register.
-
-What:		/sys/bus/coresight/devices/etm<N>/sshot_pe_ctrl
-Date:		December 2019
-KernelVersion:	5.5
-Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(RW) Access the selected single show PE comparator control
-		register.
-
-What:		/sys/bus/coresight/devices/etm<N>/mgmt/trcoslsr
+What:		/sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcoslsr
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 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<N>/mgmt/trcpdcr
+What:		/sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcpdcr
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 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<N>/mgmt/trcpdsr
+What:		/sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcpdsr
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 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<N>/mgmt/trclsr
+What:		/sys/bus/coresight/devices/<memory_map>.etm/mgmt/trclsr
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 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<N>/mgmt/trcauthstatus
+What:		/sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcauthstatus
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 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<N>/mgmt/trcdevid
+What:		/sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcdevid
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 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<N>/mgmt/trcdevtype
+What:		/sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcdevtype
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 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<N>/mgmt/trcpidr0
+What:		/sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcpidr0
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 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<N>/mgmt/trcpidr1
+What:		/sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcpidr1
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 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<N>/mgmt/trcpidr2
+What:		/sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcpidr2
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 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<N>/mgmt/trcpidr3
+What:		/sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcpidr3
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 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<N>/mgmt/trcconfig
+What:		/sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcconfig
 Date:		February 2016
 KernelVersion:	4.07
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description:	(R) Print the content of the trace configuration register
 		(0x010) as currently set by SW.
 
-What:		/sys/bus/coresight/devices/etm<N>/mgmt/trctraceid
+What:		/sys/bus/coresight/devices/<memory_map>.etm/mgmt/trctraceid
 Date:		February 2016
 KernelVersion:	4.07
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description:	(R) Print the content of the trace ID register (0x040).
 
-What:		/sys/bus/coresight/devices/etm<N>/trcidr/trcidr0
+What:		/sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr0
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 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<N>/trcidr/trcidr1
+What:		/sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr1
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 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<N>/trcidr/trcidr2
+What:		/sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr2
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
@@ -441,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<N>/trcidr/trcidr3
+What:		/sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr3
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
@@ -450,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<N>/trcidr/trcidr4
+What:		/sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr4
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 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<N>/trcidr/trcidr5
+What:		/sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr5
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 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<N>/trcidr/trcidr8
+What:		/sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr8
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 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<N>/trcidr/trcidr9
+What:		/sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr9
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 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<N>/trcidr/trcidr10
+What:		/sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr10
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 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<N>/trcidr/trcidr11
+What:		/sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr11
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
@@ -493,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<N>/trcidr/trcidr12
+What:		/sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr12
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
@@ -501,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<N>/trcidr/trcidr13
+What:		/sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr13
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>

Documentation/ABI/testing/sysfs-bus-fsi

@@ -1,25 +1,25 @@
-What:           /sys/bus/platform/devices/../fsi-master/fsi0/rescan
+What:           /sys/bus/platform/devices/fsi-master/rescan
 Date:		May 2017
 KernelVersion:  4.12
-Contact:        linux-fsi@lists.ozlabs.org
+Contact:        cbostic@linux.vnet.ibm.com
 Description:
                 Initiates a FSI master scan for all connected slave devices
 		on its links.
 
-What:           /sys/bus/platform/devices/../fsi-master/fsi0/break
+What:           /sys/bus/platform/devices/fsi-master/break
 Date:		May 2017
 KernelVersion:  4.12
-Contact:        linux-fsi@lists.ozlabs.org
+Contact:        cbostic@linux.vnet.ibm.com
 Description:
 		Sends an FSI BREAK command on a master's communication
 		link to any connnected slaves.  A BREAK resets connected
 		device's logic and preps it to receive further commands
 		from the master.
 
-What:           /sys/bus/platform/devices/../fsi-master/fsi0/slave@00:00/term
+What:           /sys/bus/platform/devices/fsi-master/slave@00:00/term
 Date:		May 2017
 KernelVersion:  4.12
-Contact:        linux-fsi@lists.ozlabs.org
+Contact:        cbostic@linux.vnet.ibm.com
 Description:
 		Sends an FSI terminate command from the master to its
 		connected slave. A terminate resets the slave's state machines
@@ -29,10 +29,10 @@ Description:
 		ongoing operation in case of an expired 'Master Time Out'
 		timer.
 
-What:           /sys/bus/platform/devices/../fsi-master/fsi0/slave@00:00/raw
+What:           /sys/bus/platform/devices/fsi-master/slave@00:00/raw
 Date:		May 2017
 KernelVersion:  4.12
-Contact:        linux-fsi@lists.ozlabs.org
+Contact:        cbostic@linux.vnet.ibm.com
 Description:
 		Provides a means of reading/writing a 32 bit value from/to a
 		specified FSI bus address.

Documentation/ABI/testing/sysfs-bus-iio

@@ -753,8 +753,6 @@ What:		/sys/.../events/in_illuminance0_thresh_falling_value
 what:		/sys/.../events/in_illuminance0_thresh_rising_value
 what:		/sys/.../events/in_proximity0_thresh_falling_value
 what:		/sys/.../events/in_proximity0_thresh_rising_value
-What:		/sys/.../events/in_illuminance_thresh_rising_value
-What:		/sys/.../events/in_illuminance_thresh_falling_value
 KernelVersion:	2.6.37
 Contact:	linux-iio@vger.kernel.org
 Description:
@@ -974,7 +972,6 @@ What:		/sys/.../events/in_activity_jogging_thresh_rising_period
 What:		/sys/.../events/in_activity_jogging_thresh_falling_period
 What:		/sys/.../events/in_activity_running_thresh_rising_period
 What:		/sys/.../events/in_activity_running_thresh_falling_period
-What:		/sys/.../events/in_illuminance_thresh_either_period
 KernelVersion:	2.6.37
 Contact:	linux-iio@vger.kernel.org
 Description:
@@ -1718,24 +1715,3 @@ Description:
 		Mass concentration reading of particulate matter in ug / m3.
 		pmX consists of particles with aerodynamic diameter less or
 		equal to X micrometers.
-
-What:		/sys/bus/iio/devices/iio:deviceX/events/in_illuminance_period_available
-Date:		November 2019
-KernelVersion:	5.4
-Contact:	linux-iio@vger.kernel.org
-Description:
-		List of valid periods (in seconds) for which the light intensity
-		must be above the threshold level before interrupt is asserted.
-
-What:		/sys/bus/iio/devices/iio:deviceX/in_filter_notch_center_frequency
-KernelVersion:	5.5
-Contact:	linux-iio@vger.kernel.org
-Description:
-		Center frequency in Hz for a notch filter. Used i.e. for line
-		noise suppression.
-
-What:		/sys/bus/iio/devices/iio:deviceX/in_temp_thermocouple_type
-KernelVersion:	5.5
-Contact:	linux-iio@vger.kernel.org
-Description:
-		One of the following thermocouple types: B, E, J, K, N, R, S, T.

Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192

@@ -1,39 +0,0 @@
-What:		/sys/bus/iio/devices/iio:deviceX/ac_excitation_en
-KernelVersion:
-Contact:	linux-iio@vger.kernel.org
-Description:
-		Reading gives the state of AC excitation.
-		Writing '1' enables AC excitation.
-
-What:		/sys/bus/iio/devices/iio:deviceX/bridge_switch_en
-KernelVersion:
-Contact:	linux-iio@vger.kernel.org
-Description:
-		This bridge switch is used to disconnect it when there is a
-		need to minimize the system current consumption.
-		Reading gives the state of the bridge switch.
-		Writing '1' enables the bridge switch.
-
-What:		/sys/bus/iio/devices/iio:deviceX/in_voltagex_sys_calibration
-KernelVersion:
-Contact:	linux-iio@vger.kernel.org
-Description:
-		Initiates the system calibration procedure. This is done on a
-		single channel at a time. Write '1' to start the calibration.
-
-What:		/sys/bus/iio/devices/iio:deviceX/in_voltagex_sys_calibration_mode_available
-KernelVersion:
-Contact:	linux-iio@vger.kernel.org
-Description:
-		Reading returns a list with the possible calibration modes.
-		There are two available options:
-		"zero_scale" - calibrate to zero scale
-		"full_scale" - calibrate to full scale
-
-What:		/sys/bus/iio/devices/iio:deviceX/in_voltagex_sys_calibration_mode
-KernelVersion:
-Contact:	linux-iio@vger.kernel.org
-Description:
-		Sets up the calibration mode used in the system calibration
-		procedure. Reading returns the current calibration mode.
-		Writing sets the system calibration mode.

Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32

@@ -13,4 +13,4 @@ Description:
 			error on writing
 		If DFSDM input is SPI Slave:
 			Reading returns value previously set.
-			Writing value before starting conversions.
+			Writing value before starting conversions.

Documentation/ABI/testing/sysfs-bus-iio-dma-buffer

@@ -1,19 +0,0 @@
-What:		/sys/bus/iio/devices/iio:deviceX/buffer/length_align_bytes
-KernelVersion:	5.4
-Contact:	linux-iio@vger.kernel.org
-Description:
-		DMA buffers tend to have a alignment requirement for the
-		buffers. If this alignment requirement is not met samples might
-		be dropped from the buffer.
-
-		This property reports the alignment requirements in bytes.
-		This means that the buffer size in bytes needs to be a integer
-		multiple of the number reported by this file.
-
-		The alignment requirements in number of sample sets will depend
-		on the enabled channels and the bytes per channel. This means
-		that the alignment requirement in samples sets might change
-		depending on which and how many channels are enabled. Whereas
-		the alignment requirement reported in bytes by this property
-		will remain static and does not depend on which channels are
-		enabled.

Documentation/ABI/testing/sysfs-bus-iio-timer-stm32

@@ -91,6 +91,29 @@ Description:
 		When counting down the counter start from preset value
 		and fire event when reach 0.
 
+What:		/sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
+KernelVersion:	4.12
+Contact:	benjamin.gaignard@st.com
+Description:
+		Reading returns the list possible quadrature modes.
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode
+KernelVersion:	4.12
+Contact:	benjamin.gaignard@st.com
+Description:
+		Configure the device counter quadrature modes:
+		channel_A:
+			Encoder A input servers as the count input and B as
+			the UP/DOWN direction control input.
+
+		channel_B:
+			Encoder B input serves as the count input and A as
+			the UP/DOWN direction control input.
+
+		quadrature:
+			Encoder A and B inputs are mixed to get direction
+			and count with a scale of 0.25.
+
 What:		/sys/bus/iio/devices/iio:deviceX/in_count_enable_mode_available
 KernelVersion:	4.12
 Contact:	benjamin.gaignard@st.com

Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc

@@ -12,8 +12,7 @@ Description:	(RW) Configure MSC operating mode:
 		  - "single", for contiguous buffer mode (high-order alloc);
 		  - "multi", for multiblock mode;
 		  - "ExI", for DCI handler mode;
-		  - "debug", for debug mode;
-		  - any of the currently loaded buffer sinks.
+		  - "debug", for debug mode.
 		If operating mode changes, existing buffer is deallocated,
 		provided there are no active users and tracing is not enabled,
 		otherwise the write will fail.

Documentation/ABI/testing/sysfs-bus-mdio

@@ -1,63 +0,0 @@
-What:          /sys/bus/mdio_bus/devices/.../statistics/
-Date:          January 2020
-KernelVersion: 5.6
-Contact:       netdev@vger.kernel.org
-Description:
-		This folder contains statistics about global and per
-		MDIO bus address statistics.
-
-What:          /sys/bus/mdio_bus/devices/.../statistics/transfers
-Date:          January 2020
-KernelVersion: 5.6
-Contact:       netdev@vger.kernel.org
-Description:
-		Total number of transfers for this MDIO bus.
-
-What:          /sys/bus/mdio_bus/devices/.../statistics/errors
-Date:          January 2020
-KernelVersion: 5.6
-Contact:       netdev@vger.kernel.org
-Description:
-		Total number of transfer errors for this MDIO bus.
-
-What:          /sys/bus/mdio_bus/devices/.../statistics/writes
-Date:          January 2020
-KernelVersion: 5.6
-Contact:       netdev@vger.kernel.org
-Description:
-		Total number of write transactions for this MDIO bus.
-
-What:          /sys/bus/mdio_bus/devices/.../statistics/reads
-Date:          January 2020
-KernelVersion: 5.6
-Contact:       netdev@vger.kernel.org
-Description:
-		Total number of read transactions for this MDIO bus.
-
-What:          /sys/bus/mdio_bus/devices/.../statistics/transfers_<addr>
-Date:          January 2020
-KernelVersion: 5.6
-Contact:       netdev@vger.kernel.org
-Description:
-		Total number of transfers for this MDIO bus address.
-
-What:          /sys/bus/mdio_bus/devices/.../statistics/errors_<addr>
-Date:          January 2020
-KernelVersion: 5.6
-Contact:       netdev@vger.kernel.org
-Description:
-		Total number of transfer errors for this MDIO bus address.
-
-What:          /sys/bus/mdio_bus/devices/.../statistics/writes_<addr>
-Date:          January 2020
-KernelVersion: 5.6
-Contact:       netdev@vger.kernel.org
-Description:
-		Total number of write transactions for this MDIO bus address.
-
-What:          /sys/bus/mdio_bus/devices/.../statistics/reads_<addr>
-Date:          January 2020
-KernelVersion: 5.6
-Contact:       netdev@vger.kernel.org
-Description:
-		Total number of read transactions for this MDIO bus address.

Documentation/ABI/testing/sysfs-bus-mei

@@ -4,7 +4,7 @@ KernelVersion:	3.10
 Contact:	Samuel Ortiz <sameo@linux.intel.com>
 		linux-mei@linux.intel.com
 Description:	Stores the same MODALIAS value emitted by uevent
-		Format: mei:<mei device name>:<device uuid>:<protocol version>
+		Format: mei:<mei device name>:<device uuid>:
 
 What:		/sys/bus/mei/devices/.../name
 Date:		May 2015
@@ -26,24 +26,3 @@ KernelVersion:	4.3
 Contact:	Tomas Winkler <tomas.winkler@intel.com>
 Description:	Stores mei client protocol version
 		Format: %d
-
-What:		/sys/bus/mei/devices/.../max_conn
-Date:		Nov 2019
-KernelVersion:	5.5
-Contact:	Tomas Winkler <tomas.winkler@intel.com>
-Description:	Stores mei client maximum number of connections
-		Format: %d
-
-What:		/sys/bus/mei/devices/.../fixed
-Date:		Nov 2019
-KernelVersion:	5.5
-Contact:	Tomas Winkler <tomas.winkler@intel.com>
-Description:	Stores mei client fixed address, if any
-		Format: %d
-
-What:		/sys/bus/mei/devices/.../max_len
-Date:		Nov 2019
-KernelVersion:	5.5
-Contact:	Tomas Winkler <tomas.winkler@intel.com>
-Description:	Stores mei client maximum message length
-		Format: %d

Documentation/ABI/testing/sysfs-bus-moxtet-devices

@@ -1,17 +0,0 @@
-What:		/sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_description
-Date:		March 2019
-KernelVersion:	5.3
-Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(R) Moxtet module description. Format: string
-
-What:		/sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_id
-Date:		March 2019
-KernelVersion:	5.3
-Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(R) Moxtet module ID. Format: %x
-
-What:		/sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_name
-Date:		March 2019
-KernelVersion:	5.3
-Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(R) Moxtet module name. Format: string

Documentation/ABI/testing/sysfs-bus-pci

@@ -347,16 +347,3 @@ Description:
 		If the device has any Peer-to-Peer memory registered, this
 	        file contains a '1' if the memory has been published for
 		use outside the driver that owns the device.
-
-What:		/sys/bus/pci/devices/.../link/clkpm
-		/sys/bus/pci/devices/.../link/l0s_aspm
-		/sys/bus/pci/devices/.../link/l1_aspm
-		/sys/bus/pci/devices/.../link/l1_1_aspm
-		/sys/bus/pci/devices/.../link/l1_2_aspm
-		/sys/bus/pci/devices/.../link/l1_1_pcipm
-		/sys/bus/pci/devices/.../link/l1_2_pcipm
-Date:		October 2019
-Contact:	Heiner Kallweit <hkallweit1@gmail.com>
-Description:	If ASPM is supported for an endpoint, these files can be
-		used to disable or enable the individual power management
-		states. Write y/1/on to enable, n/0/off to disable.

Documentation/ABI/testing/sysfs-bus-thunderbolt

@@ -80,14 +80,6 @@ Contact:	thunderbolt-software@lists.01.org
 Description:	This attribute contains 1 if Thunderbolt device was already
 		authorized on boot and 0 otherwise.
 
-What: /sys/bus/thunderbolt/devices/.../generation
-Date:		Jan 2020
-KernelVersion:	5.5
-Contact:	Christian Kellner <christian@kellner.me>
-Description:	This attribute contains the generation of the Thunderbolt
-		controller associated with the device. It will contain 4
-		for USB4.
-
 What: /sys/bus/thunderbolt/devices/.../key
 Date:		Sep 2017
 KernelVersion:	4.13
@@ -112,34 +104,6 @@ Contact:	thunderbolt-software@lists.01.org
 Description:	This attribute contains name of this device extracted from
 		the device DROM.
 
-What:		/sys/bus/thunderbolt/devices/.../rx_speed
-Date:		Jan 2020
-KernelVersion:	5.5
-Contact:	Mika Westerberg <mika.westerberg@linux.intel.com>
-Description:	This attribute reports the device RX speed per lane.
-		All RX lanes run at the same speed.
-
-What:		/sys/bus/thunderbolt/devices/.../rx_lanes
-Date:		Jan 2020
-KernelVersion:	5.5
-Contact:	Mika Westerberg <mika.westerberg@linux.intel.com>
-Description:	This attribute reports number of RX lanes the device is
-		using simultaneusly through its upstream port.
-
-What:		/sys/bus/thunderbolt/devices/.../tx_speed
-Date:		Jan 2020
-KernelVersion:	5.5
-Contact:	Mika Westerberg <mika.westerberg@linux.intel.com>
-Description:	This attribute reports the TX speed per lane.
-		All TX lanes run at the same speed.
-
-What:		/sys/bus/thunderbolt/devices/.../tx_lanes
-Date:		Jan 2020
-KernelVersion:	5.5
-Contact:	Mika Westerberg <mika.westerberg@linux.intel.com>
-Description:	This attribute reports number of TX lanes the device is
-		using simultaneusly through its upstream port.
-
 What:		/sys/bus/thunderbolt/devices/.../vendor
 Date:		Sep 2017
 KernelVersion:	4.13

Documentation/ABI/testing/sysfs-class-backlight

@@ -1,26 +0,0 @@
-What:		/sys/class/backlight/<backlight>/scale
-Date:		July 2019
-KernelVersion:	5.4
-Contact:	Daniel Thompson <daniel.thompson@linaro.org>
-Description:
-		Description of the scale of the brightness curve.
-
-		The human eye senses brightness approximately logarithmically,
-		hence linear changes in brightness are perceived as being
-		non-linear. To achieve a linear perception of brightness changes
-		controls like sliders need to apply a logarithmic mapping for
-		backlights with a linear brightness curve.
-
-		Possible values of the attribute are:
-
-		unknown
-		  The scale of the brightness curve is unknown.
-
-		linear
-		  The brightness changes linearly with each step. Brightness
-		  controls should apply a logarithmic mapping for a linear
-		  perception.
-
-		non-linear
-		  The brightness changes non-linearly with each step. Brightness
-		  controls should use a linear mapping for a linear perception.

Documentation/ABI/testing/sysfs-class-devfreq

@@ -7,13 +7,6 @@ Description:
 		The name of devfreq object denoted as ... is same as the
 		name of device using devfreq.
 
-What:		/sys/class/devfreq/.../name
-Date:		November 2019
-Contact:	Chanwoo Choi <cw00.choi@samsung.com>
-Description:
-		The /sys/class/devfreq/.../name shows the name of device
-		of the corresponding devfreq object.
-
 What:		/sys/class/devfreq/.../governor
 Date:		September 2011
 Contact:	MyungJoo Ham <myungjoo.ham@samsung.com>
@@ -55,15 +48,12 @@ What:		/sys/class/devfreq/.../trans_stat
 Date:		October 2012
 Contact:	MyungJoo Ham <myungjoo.ham@samsung.com>
 Description:
-		This ABI shows or clears the statistics of devfreq behavior
-		on a specific device. It shows the time spent in each state
-		and the number of transitions between states.
+		This ABI shows the statistics of devfreq behavior on a
+		specific device. It shows the time spent in each state and
+		the number of transitions between states.
 		In order to activate this ABI, the devfreq target device
 		driver should provide the list of available frequencies
-		with its profile. If need to reset the statistics of devfreq
-		behavior on a specific device, enter 0(zero) to 'trans_stat'
-		as following:
-			echo 0 > /sys/class/devfreq/.../trans_stat
+		with its profile.
 
 What:		/sys/class/devfreq/.../userspace/set_freq
 Date:		September 2011

Documentation/ABI/testing/sysfs-class-led-driver-el15203000

@@ -1,139 +0,0 @@
-What:		/sys/class/leds/<led>/hw_pattern
-Date:		September 2019
-KernelVersion:	5.5
-Description:
-		Specify a hardware pattern for the EL15203000 LED.
-		The LEDs board supports only predefined patterns by firmware
-		for specific LEDs.
-
-		Breathing mode for Screen frame light tube:
-		"0 4000 1 4000"
-
-		    ^
-		    |
-		Max-|     ---
-		    |    /   \
-		    |   /     \
-		    |  /       \     /
-		    | /         \   /
-		Min-|-           ---
-		    |
-		    0------4------8--> time (sec)
-
-		Cascade mode for Pipe LED:
-		"1 800 2 800 4 800 8 800 16 800"
-
-		      ^
-		      |
-		0 On -|----+                   +----+                   +---
-		      |    |                   |    |                   |
-		  Off-|    +-------------------+    +-------------------+
-		      |
-		1 On -|    +----+                   +----+
-		      |    |    |                   |    |
-		  Off |----+    +-------------------+    +------------------
-		      |
-		2 On -|         +----+                   +----+
-		      |         |    |                   |    |
-		  Off-|---------+    +-------------------+    +-------------
-		      |
-		3 On -|              +----+                   +----+
-		      |              |    |                   |    |
-		  Off-|--------------+    +-------------------+    +--------
-		      |
-		4 On -|                   +----+                   +----+
-		      |                   |    |                   |    |
-		  Off-|-------------------+    +-------------------+    +---
-		      |
-		      0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
-
-		Inverted cascade mode for Pipe LED:
-		"30 800 29 800 27 800 23 800 15 800"
-
-		      ^
-		      |
-		0 On -|    +-------------------+    +-------------------+
-		      |    |                   |    |                   |
-		  Off-|----+                   +----+                   +---
-		      |
-		1 On -|----+    +-------------------+    +------------------
-		      |    |    |                   |    |
-		  Off |    +----+                   +----+
-		      |
-		2 On -|---------+    +-------------------+    +-------------
-		      |         |    |                   |    |
-		  Off-|         +----+                   +----+
-		      |
-		3 On -|--------------+    +-------------------+    +--------
-		      |              |    |                   |    |
-		  Off-|              +----+                   +----+
-		      |
-		4 On -|-------------------+    +-------------------+    +---
-		      |                   |    |                   |    |
-		  Off-|                   +----+                   +----+
-		      |
-		      0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
-
-		Bounce mode for Pipe LED:
-		"1 800 2 800 4 800 8 800 16 800 16 800 8 800 4 800 2 800 1 800"
-
-		      ^
-		      |
-		0 On -|----+                                       +--------
-		      |    |                                       |
-		  Off-|    +---------------------------------------+
-		      |
-		1 On -|    +----+                             +----+
-		      |    |    |                             |    |
-		  Off |----+    +-----------------------------+    +--------
-		      |
-		2 On -|         +----+                   +----+
-		      |         |    |                   |    |
-		  Off-|---------+    +-------------------+    +-------------
-		      |
-		3 On -|              +----+         +----+
-		      |              |    |         |    |
-		  Off-|--------------+    +---------+    +------------------
-		      |
-		4 On -|                   +---------+
-		      |                   |         |
-		  Off-|-------------------+         +-----------------------
-		      |
-		      0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
-
-		Inverted bounce mode for Pipe LED:
-		"30 800 29 800 27 800 23 800 15 800 15 800 23 800 27 800 29 800 30 800"
-
-		      ^
-		      |
-		0 On -|    +---------------------------------------+
-		      |    |                                       |
-		  Off-|----+                                       +--------
-		      |
-		1 On -|----+    +-----------------------------+    +--------
-		      |    |    |                             |    |
-		  Off |    +----+                             +----+
-		      |
-		2 On -|---------+    +-------------------+    +-------------
-		      |         |    |                   |    |
-		  Off-|         +----+                   +----+
-		      |
-		3 On -|--------------+    +---------+    +------------------
-		      |              |    |         |    |
-		  Off-|              +----+         +----+
-		      |
-		4 On -|-------------------+         +-----------------------
-		      |                   |         |
-		  Off-|                   +---------+
-		      |
-		      0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
-
-What:		/sys/class/leds/<led>/repeat
-Date:		September 2019
-KernelVersion:	5.5
-Description:
-		EL15203000 supports only indefinitely patterns,
-		so this file should always store -1.
-
-		For more info, please see:
-		Documentation/ABI/testing/sysfs-class-led-trigger-pattern

Documentation/ABI/testing/sysfs-class-mei

@@ -80,13 +80,3 @@ Description:	Display the ME device state.
 		DISABLED
 		POWER_DOWN
 		POWER_UP
-
-What:		/sys/class/mei/meiN/trc
-Date:		Nov 2019
-KernelVersion:	5.5
-Contact:	Tomas Winkler <tomas.winkler@intel.com>
-Description:	Display trc status register content
-
-		The ME FW writes Glitch Detection HW (TRC)
-		status information into trc status register
-		for BIOS and OS to monitor fw health.

Documentation/ABI/testing/sysfs-class-net-statistics

@@ -51,14 +51,6 @@ Description:
 		packet processing. See the network driver for the exact
 		meaning of this value.
 
-What:		/sys/class/<iface>/statistics/rx_errors
-Date:		April 2005
-KernelVersion:	2.6.12
-Contact:	netdev@vger.kernel.org
-Description:
-		Indicates the number of receive errors on this network device.
-		See the network driver for the exact meaning of this value.
-
 What:		/sys/class/<iface>/statistics/rx_fifo_errors
 Date:		April 2005
 KernelVersion:	2.6.12
@@ -96,14 +88,6 @@ Description:
 		due to lack of capacity in the receive side. See the network
 		driver for the exact meaning of this value.
 
-What:		/sys/class/<iface>/statistics/rx_nohandler
-Date:		February 2016
-KernelVersion:	4.6
-Contact:	netdev@vger.kernel.org
-Description:
-		Indicates the number of received packets that were dropped on
-		an inactive device by the network core.
-
 What:		/sys/class/<iface>/statistics/rx_over_errors
 Date:		April 2005
 KernelVersion:	2.6.12

Documentation/ABI/testing/sysfs-class-power

@@ -189,8 +189,7 @@ Description:
 		Access: Read
 		Valid values: "Unknown", "Good", "Overheat", "Dead",
 			      "Over voltage", "Unspecified failure", "Cold",
-			      "Watchdog timer expire", "Safety timer expire",
-			      "Over current"
+			      "Watchdog timer expire", "Safety timer expire"
 
 What:		/sys/class/power_supply/<supply_name>/precharge_current
 Date:		June 2017

Documentation/ABI/testing/sysfs-class-remoteproc

@@ -48,13 +48,3 @@ Description:	Remote processor state
 
 		Writing "stop" will attempt to halt the remote processor and
 		return it to the "offline" state.
-
-What:		/sys/class/remoteproc/.../name
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Suman Anna <s-anna@ti.com>
-Description:	Remote processor name
-
-		Reports the name of the remote processor. This can be used by
-		userspace in exactly identifying a remote processor and ease
-		up the usage in modifying the 'firmware' or 'state' files.

Documentation/ABI/testing/sysfs-class-wakeup

@@ -1,76 +0,0 @@
-What:		/sys/class/wakeup/
-Date:		June 2019
-Contact:	Tri Vo <trong@android.com>
-Description:
-		The /sys/class/wakeup/ directory contains pointers to all
-		wakeup sources in the kernel at that moment in time.
-
-What:		/sys/class/wakeup/.../name
-Date:		June 2019
-Contact:	Tri Vo <trong@android.com>
-Description:
-		This file contains the name of the wakeup source.
-
-What:		/sys/class/wakeup/.../active_count
-Date:		June 2019
-Contact:	Tri Vo <trong@android.com>
-Description:
-		This file contains the number of times the wakeup source was
-		activated.
-
-What:		/sys/class/wakeup/.../event_count
-Date:		June 2019
-Contact:	Tri Vo <trong@android.com>
-Description:
-		This file contains the number of signaled wakeup events
-		associated with the wakeup source.
-
-What:		/sys/class/wakeup/.../wakeup_count
-Date:		June 2019
-Contact:	Tri Vo <trong@android.com>
-Description:
-		This file contains the number of times the wakeup source might
-		abort suspend.
-
-What:		/sys/class/wakeup/.../expire_count
-Date:		June 2019
-Contact:	Tri Vo <trong@android.com>
-Description:
-		This file contains the number of times the wakeup source's
-		timeout has expired.
-
-What:		/sys/class/wakeup/.../active_time_ms
-Date:		June 2019
-Contact:	Tri Vo <trong@android.com>
-Description:
-		This file contains the amount of time the wakeup source has
-		been continuously active, in milliseconds.  If the wakeup
-		source is not active, this file contains '0'.
-
-What:		/sys/class/wakeup/.../total_time_ms
-Date:		June 2019
-Contact:	Tri Vo <trong@android.com>
-Description:
-		This file contains the total amount of time this wakeup source
-		has been active, in milliseconds.
-
-What:		/sys/class/wakeup/.../max_time_ms
-Date:		June 2019
-Contact:	Tri Vo <trong@android.com>
-Description:
-		This file contains the maximum amount of time this wakeup
-		source has been continuously active, in milliseconds.
-
-What:		/sys/class/wakeup/.../last_change_ms
-Date:		June 2019
-Contact:	Tri Vo <trong@android.com>
-Description:
-		This file contains the monotonic clock time when the wakeup
-		source was touched last time, in milliseconds.
-
-What:		/sys/class/wakeup/.../prevent_suspend_time_ms
-Date:		June 2019
-Contact:	Tri Vo <trong@android.com>
-Description:
-		The file contains the total amount of time this wakeup source
-		has been preventing autosleep, in milliseconds.

Documentation/ABI/testing/sysfs-class-watchdog

@@ -17,13 +17,8 @@ What:		/sys/class/watchdog/watchdogn/nowayout
 Date:		August 2015
 Contact:	Wim Van Sebroeck <wim@iguana.be>
 Description:
-		It is a read/write file. While reading, it gives '1'
-		if the device has the nowayout feature set, otherwise
-		it gives '0'. Writing a '1' to the file enables the
-		nowayout feature. Once set, the nowayout feature
-		cannot be disabled, so writing a '0' either has no
-		effect (if the feature was already disabled) or
-		results in a permission error.
+		It is a read only file. While reading, it gives '1' if that
+		device supports nowayout feature else, it gives '0'.
 
 What:		/sys/class/watchdog/watchdogn/state
 Date:		August 2015
@@ -77,37 +72,3 @@ Description:
 		It is a read/write file. When read, the currently assigned
 		pretimeout governor is returned.  When written, it sets
 		the pretimeout governor.
-
-What:		/sys/class/watchdog/watchdog1/access_cs0
-Date:		August 2019
-Contact:	Ivan Mikhaylov <i.mikhaylov@yadro.com>,
-		Alexander Amelkin <a.amelkin@yadro.com>
-Description:
-		It is a read/write file. This attribute exists only if the
-		system has booted from the alternate flash chip due to
-		expiration of a watchdog timer of AST2400/AST2500 when
-		alternate boot function was enabled with 'aspeed,alt-boot'
-		devicetree option for that watchdog or with an appropriate
-		h/w strapping (for WDT2 only).
-
-		At alternate flash the 'access_cs0' sysfs node provides:
-			ast2400: a way to get access to the primary SPI flash
-				chip at CS0 after booting from the alternate
-				chip at CS1.
-			ast2500: a way to restore the normal address mapping
-				from (CS0->CS1, CS1->CS0) to (CS0->CS0,
-				CS1->CS1).
-
-		Clearing the boot code selection and timeout counter also
-		resets to the initial state the chip select line mapping. When
-		the SoC is in normal mapping state (i.e. booted from CS0),
-		clearing those bits does nothing for both versions of the SoC.
-		For alternate boot mode (booted from CS1 due to wdt2
-		expiration) the behavior differs as described above.
-
-		This option can be used with wdt2 (watchdog1) only.
-
-		When read, the current status of the boot code selection is
-		shown. When written with any non-zero value, it clears
-		the boot code selection and the timeout counter, which results
-		in chipselect reset for AST2400/AST2500.

Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu

@@ -1,128 +0,0 @@
-	Intel Stratix10 Remote System Update (RSU) device attributes
-
-What:		/sys/devices/platform/stratix10-rsu.0/current_image
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Richard Gong <richard.gong@linux.intel.com>
-Description:
-		(RO) the address in flash of currently running image.
-
-What:		/sys/devices/platform/stratix10-rsu.0/fail_image
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Richard Gong <richard.gong@linux.intel.com>
-Description:
-		(RO) the address in flash of failed image.
-
-What:		/sys/devices/platform/stratix10-rsu.0/state
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Richard Gong <richard.gong@linux.intel.com>
-Description:
-		(RO) the state of RSU system.
-		The state field has two parts: major error code in
-		upper 16 bits and minor error code in lower 16 bits.
-
-		b[15:0]
-			Currently used only when major error is 0xF006
-			(CPU watchdog timeout), in which case the minor
-			error code is the value reported by CPU to
-			firmware through the RSU notify command before
-			the watchdog timeout occurs.
-
-		b[31:16]
-			0xF001	bitstream error
-			0xF002	hardware access failure
-			0xF003	bitstream corruption
-			0xF004	internal error
-			0xF005	device error
-			0xF006	CPU watchdog timeout
-			0xF007	internal unknown error
-
-What:		/sys/devices/platform/stratix10-rsu.0/version
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Richard Gong <richard.gong@linux.intel.com>
-Description:
-		(RO) the version number of RSU firmware. 19.3 or late
-		version includes information about the firmware which
-		reported the error.
-
-		pre 19.3:
-			b[31:0]
-				0x0	version number
-
-		19.3 or late:
-			b[15:0]
-				0x1	version number
-			b[31:16]
-				0x0	no error
-				0x0DCF	Decision CMF error
-				0x0ACF	Application CMF error
-
-What:		/sys/devices/platform/stratix10-rsu.0/error_location
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Richard Gong <richard.gong@linux.intel.com>
-Description:
-		(RO) the error offset inside the image that failed.
-
-What:		/sys/devices/platform/stratix10-rsu.0/error_details
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Richard Gong <richard.gong@linux.intel.com>
-Description:
-		(RO) error code.
-
-What:		/sys/devices/platform/stratix10-rsu.0/retry_counter
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Richard Gong <richard.gong@linux.intel.com>
-Description:
-		(RO) the current image's retry counter, which is used by
-		user to know how many times the images is still allowed
-		to reload itself before giving up and starting RSU
-		fail-over flow.
-
-What:		/sys/devices/platform/stratix10-rsu.0/reboot_image
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Richard Gong <richard.gong@linux.intel.com>
-Description:
-		(WO) the address in flash of image to be loaded on next
-		reboot command.
-
-What:		/sys/devices/platform/stratix10-rsu.0/notify
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Richard Gong <richard.gong@linux.intel.com>
-Description:
-		(WO) client to notify firmware with different actions.
-
-		b[15:0]
-			inform firmware the current software execution
-			stage.
-			0	the first stage bootloader didn't run or
-				didn't reach the point of launching second
-				stage bootloader.
-			1	failed in second bootloader or didn't get
-				to the point of launching the operating
-				system.
-			2	both first and second stage bootloader ran
-				and the operating system launch was
-				attempted.
-
-		b[16]
-			1	firmware to reset current image retry
-				counter.
-			0	no action.
-
-		b[17]
-			1	firmware to clear RSU log
-			0	no action.
-
-		b[18]
-			this is negative logic
-			1	no action
-			0	firmware record the notify code defined
-				in b[15:0].

Documentation/ABI/testing/sysfs-devices-power

@@ -260,12 +260,3 @@ Description:
 
 		This attribute has no effect on system-wide suspend/resume and
 		hibernation.
-
-What:		/sys/devices/.../power/runtime_status
-Date:		April 2010
-Contact:	Rafael J. Wysocki <rjw@rjwysocki.net>
-Description:
-		The /sys/devices/.../power/runtime_status attribute contains
-		the current runtime PM status of the device, which may be
-		"suspended", "suspending", "resuming", "active", "error" (fatal
-		error), or "unsupported" (runtime PM is disabled).

Documentation/ABI/testing/sysfs-devices-soc

@@ -26,13 +26,6 @@ Description:
 		Read-only attribute common to all SoCs. Contains SoC family name
 		(e.g. DB8500).
 
-What:		/sys/devices/socX/serial_number
-Date:		January 2019
-contact:	Bjorn Andersson <bjorn.andersson@linaro.org>
-Description:
-		Read-only attribute supported by most SoCs. Contains the SoC's
-		serial number, if available.
-
 What:		/sys/devices/socX/soc_id
 Date:		January 2012
 contact:	Lee Jones <lee.jones@linaro.org>

Documentation/ABI/testing/sysfs-devices-system-cpu

@@ -196,12 +196,6 @@ Description:
 		does not reflect it. Likewise, if one enables a deep state but a
 		lighter state still is disabled, then this has no effect.
 
-What:		/sys/devices/system/cpu/cpuX/cpuidle/stateN/default_status
-Date:		December 2019
-KernelVersion:	v5.6
-Contact:	Linux power management list <linux-pm@vger.kernel.org>
-Description:
-		(RO) The default status of this state, "enabled" or "disabled".
 
 What:		/sys/devices/system/cpu/cpuX/cpuidle/stateN/residency
 Date:		March 2014
@@ -492,9 +486,6 @@ What:		/sys/devices/system/cpu/vulnerabilities
 		/sys/devices/system/cpu/vulnerabilities/spec_store_bypass
 		/sys/devices/system/cpu/vulnerabilities/l1tf
 		/sys/devices/system/cpu/vulnerabilities/mds
-		/sys/devices/system/cpu/vulnerabilities/srbds
-		/sys/devices/system/cpu/vulnerabilities/tsx_async_abort
-		/sys/devices/system/cpu/vulnerabilities/itlb_multihit
 Date:		January 2018
 Contact:	Linux kernel mailing list <linux-kernel@vger.kernel.org>
 Description:	Information about CPU vulnerabilities
@@ -571,13 +562,3 @@ Description:	Umwait control
 			  or C0.2 state. The time is an unsigned 32-bit number.
 			  Note that a value of zero means there is no limit.
 			  Low order two bits must be zero.
-
-What:		/sys/devices/system/cpu/svm
-Date:		August 2019
-Contact:	Linux kernel mailing list <linux-kernel@vger.kernel.org>
-		Linux for PowerPC mailing list <linuxppc-dev@ozlabs.org>
-Description:	Secure Virtual Machine
-
-		If 1, it means the system is using the Protected Execution
-		Facility in POWER9 and newer processors. i.e., it is a Secure
-		Virtual Machine.

Documentation/ABI/testing/sysfs-driver-habanalabs

@@ -57,7 +57,6 @@ KernelVersion:  5.1
 Contact:        oded.gabbay@gmail.com
 Description:    Allows the user to set the maximum clock frequency for MME, TPC
                 and IC when the power management profile is set to "automatic".
-                This property is valid only for the Goya ASIC family
 
 What:           /sys/class/habanalabs/hl<n>/ic_clk
 Date:           Jan 2019
@@ -128,8 +127,8 @@ Description:    Power management profile. Values are "auto", "manual". In "auto"
                 the max clock frequency to a low value when there are no user
                 processes that are opened on the device's file. In "manual"
                 mode, the user sets the maximum clock frequency by writing to
-                ic_clk, mme_clk and tpc_clk. This property is valid only for
-                the Goya ASIC family
+                ic_clk, mme_clk and tpc_clk
+
 
 What:           /sys/class/habanalabs/hl<n>/preboot_btl_ver
 Date:           Jan 2019
@@ -187,4 +186,11 @@ What:           /sys/class/habanalabs/hl<n>/uboot_ver
 Date:           Jan 2019
 KernelVersion:  5.1
 Contact:        oded.gabbay@gmail.com
-Description:    Version of the u-boot running on the device's CPU
+Description:    Version of the u-boot running on the device's CPU
+
+What:           /sys/class/habanalabs/hl<n>/write_open_cnt
+Date:           Jan 2019
+KernelVersion:  5.1
+Contact:        oded.gabbay@gmail.com
+Description:    Displays the total number of user processes that are currently
+                opened on the device's file

Documentation/ABI/testing/sysfs-driver-pciback

@@ -11,16 +11,3 @@ Description:
                 #echo 00:19.0-E0:2:FF > /sys/bus/pci/drivers/pciback/quirks
                 will allow the guest to read and write to the configuration
                 register 0x0E.
-
-What:           /sys/bus/pci/drivers/pciback/allow_interrupt_control
-Date:           Jan 2020
-KernelVersion:  5.6
-Contact:        xen-devel@lists.xenproject.org
-Description:
-                List of devices which can have interrupt control flag (INTx,
-                MSI, MSI-X) set by a connected guest. It is meant to be set
-                only when the guest is a stubdomain hosting device model (qemu)
-                and the actual device is assigned to a HVM. It is not safe
-                (similar to permissive attribute) to set for a devices assigned
-                to a PV guest. The device is automatically removed from this
-                list when the connected pcifront terminates.

Documentation/ABI/testing/sysfs-driver-w1_therm

@@ -1,116 +0,0 @@
-What:		/sys/bus/w1/devices/.../alarms
-Date:		May 2020
-Contact:	Akira Shimahara <akira215corp@gmail.com>
-Description:
-		(RW) read or write TH and TL (Temperature High an Low) alarms.
-		Values shall be space separated and in the device range
-		(typical -55 degC to 125 degC), if not values will be trimmed
-		to device min/max capabilities. Values are integer as they are
-		stored in a 8bit register in the device. Lowest value is
-		automatically put to TL. Once set, alarms could be search at
-		master level, refer to Documentation/w1/w1_generic.rst for
-		detailed information
-Users:		any user space application which wants to communicate with
-		w1_term device
-
-
-What:		/sys/bus/w1/devices/.../eeprom
-Date:		May 2020
-Contact:	Akira Shimahara <akira215corp@gmail.com>
-Description:
-		(WO) writing that file will either trigger a save of the
-		device data to its embedded EEPROM, either restore data
-		embedded in device EEPROM. Be aware that devices support
-		limited EEPROM writing cycles (typical 50k)
-			* 'save': save device RAM to EEPROM
-			* 'restore': restore EEPROM data in device RAM
-Users:		any user space application which wants to communicate with
-		w1_term device
-
-
-What:		/sys/bus/w1/devices/.../ext_power
-Date:		May 2020
-Contact:	Akira Shimahara <akira215corp@gmail.com>
-Description:
-		(RO) return the power status by asking the device
-			* '0': device parasite powered
-			* '1': device externally powered
-			* '-xx': xx is kernel error when reading power status
-Users:		any user space application which wants to communicate with
-		w1_term device
-
-
-What:		/sys/bus/w1/devices/.../resolution
-Date:		May 2020
-Contact:	Akira Shimahara <akira215corp@gmail.com>
-Description:
-		(RW) get or set the device resolution (on supported devices,
-		if not, this entry is not present). Note that the resolution
-		will be changed only in device RAM, so it will be cleared when
-		power is lost. Trigger a 'save' to EEPROM command to keep
-		values after power-on. Read or write are :
-			* '9..12': device resolution in bit
-			or resolution to set in bit
-			* '-xx': xx is kernel error when reading the resolution
-			* Anything else: do nothing
-Users:		any user space application which wants to communicate with
-		w1_term device
-
-
-What:		/sys/bus/w1/devices/.../temperature
-Date:		May 2020
-Contact:	Akira Shimahara <akira215corp@gmail.com>
-Description:
-		(RO) return the temperature in 1/1000 degC.
-			* If a bulk read has been triggered, it will directly
-			return the temperature computed when the bulk read
-			occurred, if available. If not yet available, nothing
-			is returned (a debug kernel message is sent), you
-			should retry later on.
-			* If no bulk read has been triggered, it will trigger
-			a conversion and send the result. Note that the
-			conversion duration depend on the resolution (if
-			device support this feature). It takes 94ms in 9bits
-			resolution, 750ms for 12bits.
-Users:		any user space application which wants to communicate with
-		w1_term device
-
-
-What:		/sys/bus/w1/devices/.../w1_slave
-Date:		May 2020
-Contact:	Akira Shimahara <akira215corp@gmail.com>
-Description:
-		(RW) return the temperature in 1/1000 degC.
-		*read*: return 2 lines with the hexa output data sent on the
-		bus, return the CRC check and temperature in 1/1000 degC
-		*write* :
-			* '0' : save the 2 or 3 bytes to the device EEPROM
-			(i.e. TH, TL and config register)
-			* '9..12' : set the device resolution in RAM
-			(if supported)
-			* Anything else: do nothing
-		refer to Documentation/w1/slaves/w1_therm.rst for detailed
-		information.
-Users:		any user space application which wants to communicate with
-		w1_term device
-
-
-What:		/sys/bus/w1/devices/w1_bus_masterXX/therm_bulk_read
-Date:		May 2020
-Contact:	Akira Shimahara <akira215corp@gmail.com>
-Description:
-		(RW) trigger a bulk read conversion. read the status
-		*read*:
-			* '-1': conversion in progress on at least 1 sensor
-			* '1' :	conversion complete but at least one sensor
-				value has not been read yet
-			* '0' :	no bulk operation. Reading temperature will
-				trigger a conversion on each device
-		*write*: 'trigger': trigger a bulk read on all supporting
-			devices on the bus
-		Note that if a bulk read is sent but one sensor is not read
-		immediately, the next access to temperature on this device
-		will return the temperature measured at the time of issue
-		of the bulk read command (not the current temperature).
-Users:		any user space application which wants to communicate with
-		w1_term device

Documentation/ABI/testing/sysfs-driver-xen-blkback

@@ -25,13 +25,3 @@ Description:
                 allocated without being in use. The time is in
                 seconds, 0 means indefinitely long.
                 The default is 60 seconds.
-
-What:           /sys/module/xen_blkback/parameters/buffer_squeeze_duration_ms
-Date:           December 2019
-KernelVersion:  5.6
-Contact:        SeongJae Park <sjpark@amazon.de>
-Description:
-                When memory pressure is reported to blkback this option
-                controls the duration in milliseconds that blkback will not
-                cache any page not backed by a grant mapping.
-                The default is 10ms.

Documentation/ABI/testing/sysfs-firmware-efi

@@ -28,11 +28,3 @@ Description:	Displays the physical addresses of all EFI Configuration
 		versions are always printed first, i.e. ACPI20 comes
 		before ACPI.
 Users:		dmidecode
-
-What:		/sys/firmware/efi/tables/rci2
-Date:		July 2019
-Contact:	Narendra K <Narendra.K@dell.com>, linux-bugs@dell.com
-Description:	Displays the content of the Runtime Configuration Interface
-		Table version 2 on Dell EMC PowerEdge systems in binary format
-Users:		It is used by Dell EMC OpenManage Server Administrator tool to
-		populate BIOS setup page.

Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm

@@ -1,37 +0,0 @@
-What:		/sys/firmware/turris-mox-rwtm/board_version
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(R) Board version burned into eFuses of this Turris Mox board.
-		Format: %i
-
-What:		/sys/firmware/turris-mox-rwtm/mac_address*
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(R) MAC addresses burned into eFuses of this Turris Mox board.
-		Format: %pM
-
-What:		/sys/firmware/turris-mox-rwtm/pubkey
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(R) ECDSA public key (in pubkey hex compressed form) computed
-		as pair to the ECDSA private key burned into eFuses of this
-		Turris Mox Board.
-		Format: string
-
-What:		/sys/firmware/turris-mox-rwtm/ram_size
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(R) RAM size in MiB of this Turris Mox board as was detected
-		during manufacturing and burned into eFuses. Can be 512 or 1024.
-		Format: %i
-
-What:		/sys/firmware/turris-mox-rwtm/serial_number
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(R) Serial number burned into eFuses of this Turris Mox device.
-		Format: %016X

Documentation/ABI/testing/sysfs-fs-f2fs

@@ -1,320 +1,253 @@
 What:		/sys/fs/f2fs/<disk>/gc_max_sleep_time
 Date:		July 2013
 Contact:	"Namjae Jeon" <namjae.jeon@samsung.com>
-Description:	Controls the maximum sleep time for gc_thread. Time
-		is in milliseconds.
+Description:
+		 Controls the maximun sleep time for gc_thread. Time
+		 is in milliseconds.
 
 What:		/sys/fs/f2fs/<disk>/gc_min_sleep_time
 Date:		July 2013
 Contact:	"Namjae Jeon" <namjae.jeon@samsung.com>
-Description:	Controls the minimum sleep time for gc_thread. Time
-		is in milliseconds.
+Description:
+		 Controls the minimum sleep time for gc_thread. Time
+		 is in milliseconds.
 
 What:		/sys/fs/f2fs/<disk>/gc_no_gc_sleep_time
 Date:		July 2013
 Contact:	"Namjae Jeon" <namjae.jeon@samsung.com>
-Description:	Controls the default sleep time for gc_thread. Time
-		is in milliseconds.
+Description:
+		 Controls the default sleep time for gc_thread. Time
+		 is in milliseconds.
 
 What:		/sys/fs/f2fs/<disk>/gc_idle
 Date:		July 2013
 Contact:	"Namjae Jeon" <namjae.jeon@samsung.com>
-Description:	Controls the victim selection policy for garbage collection.
-		Setting gc_idle = 0(default) will disable this option. Setting
-		gc_idle = 1 will select the Cost Benefit approach & setting
-		gc_idle = 2 will select the greedy approach.
+Description:
+		 Controls the victim selection policy for garbage collection.
 
 What:		/sys/fs/f2fs/<disk>/reclaim_segments
 Date:		October 2013
 Contact:	"Jaegeuk Kim" <jaegeuk.kim@samsung.com>
-Description:	This parameter controls the number of prefree segments to be
-		reclaimed. If the number of prefree segments is larger than
-		the number of segments in the proportion to the percentage
-		over total volume size, f2fs tries to conduct checkpoint to
-		reclaim the prefree segments to free segments.
-		By default, 5% over total # of segments.
-
-What:		/sys/fs/f2fs/<disk>/main_blkaddr
-Date:		November 2019
-Contact:	"Ramon Pantin" <pantin@google.com>
 Description:
-		 Shows first block address of MAIN area.
+		 Controls the issue rate of segment discard commands.
 
 What:		/sys/fs/f2fs/<disk>/ipu_policy
 Date:		November 2013
 Contact:	"Jaegeuk Kim" <jaegeuk.kim@samsung.com>
-Description:	Controls the in-place-update policy.
-		updates in f2fs. User can set:
-		0x01: F2FS_IPU_FORCE, 0x02: F2FS_IPU_SSR,
-		0x04: F2FS_IPU_UTIL,  0x08: F2FS_IPU_SSR_UTIL,
-		0x10: F2FS_IPU_FSYNC, 0x20: F2FS_IPU_ASYNC,
-		0x40: F2FS_IPU_NOCACHE.
-		Refer segment.h for details.
+Description:
+		 Controls the in-place-update policy.
 
 What:		/sys/fs/f2fs/<disk>/min_ipu_util
 Date:		November 2013
 Contact:	"Jaegeuk Kim" <jaegeuk.kim@samsung.com>
-Description:	Controls the FS utilization condition for the in-place-update
-		policies. It is used by F2FS_IPU_UTIL and F2FS_IPU_SSR_UTIL policies.
+Description:
+		 Controls the FS utilization condition for the in-place-update
+		 policies.
 
 What:		/sys/fs/f2fs/<disk>/min_fsync_blocks
 Date:		September 2014
 Contact:	"Jaegeuk Kim" <jaegeuk@kernel.org>
-Description:	Controls the dirty page count condition for the in-place-update
-		policies.
+Description:
+		 Controls the dirty page count condition for the in-place-update
+		 policies.
 
 What:		/sys/fs/f2fs/<disk>/min_seq_blocks
 Date:		August 2018
 Contact:	"Jaegeuk Kim" <jaegeuk@kernel.org>
-Description:	Controls the dirty page count condition for batched sequential
-		writes in writepages.
+Description:
+		 Controls the dirty page count condition for batched sequential
+		 writes in ->writepages.
+
 
 What:		/sys/fs/f2fs/<disk>/min_hot_blocks
 Date:		March 2017
 Contact:	"Jaegeuk Kim" <jaegeuk@kernel.org>
-Description:	Controls the dirty page count condition for redefining hot data.
+Description:
+		 Controls the dirty page count condition for redefining hot data.
 
 What:		/sys/fs/f2fs/<disk>/min_ssr_sections
 Date:		October 2017
 Contact:	"Chao Yu" <yuchao0@huawei.com>
-Description:	Controls the free section threshold to trigger SSR allocation.
-		If this is large, SSR mode will be enabled early.
+Description:
+		 Controls the fee section threshold to trigger SSR allocation.
 
 What:		/sys/fs/f2fs/<disk>/max_small_discards
 Date:		November 2013
 Contact:	"Jaegeuk Kim" <jaegeuk.kim@samsung.com>
-Description:	Controls the issue rate of discard commands that consist of small
-		blocks less than 2MB. The candidates to be discarded are cached until
-		checkpoint is triggered, and issued during the checkpoint.
-		By default, it is disabled with 0.
+Description:
+		 Controls the issue rate of small discard commands.
 
-What:		/sys/fs/f2fs/<disk>/discard_granularity
-Date:		July 2017
-Contact:	"Chao Yu" <yuchao0@huawei.com>
-Description:	Controls discard granularity of inner discard thread. Inner thread
+What:          /sys/fs/f2fs/<disk>/discard_granularity
+Date:          July 2017
+Contact:       "Chao Yu" <yuchao0@huawei.com>
+Description:
+		Controls discard granularity of inner discard thread, inner thread
 		will not issue discards with size that is smaller than granularity.
-		The unit size is one block(4KB), now only support configuring
-		in range of [1, 512]. Default value is 4(=16KB).
+		The unit size is one block, now only support configuring in range
+		of [1, 512].
 
-What:		/sys/fs/f2fs/<disk>/umount_discard_timeout
-Date:		January 2019
-Contact:	"Jaegeuk Kim" <jaegeuk@kernel.org>
-Description:	Set timeout to issue discard commands during umount.
-	        Default: 5 secs
+What:          /sys/fs/f2fs/<disk>/umount_discard_timeout
+Date:          January 2019
+Contact:       "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description:
+		Set timeout to issue discard commands during umount.
+		Default: 5 secs
 
 What:		/sys/fs/f2fs/<disk>/max_victim_search
 Date:		January 2014
 Contact:	"Jaegeuk Kim" <jaegeuk.kim@samsung.com>
-Description:	Controls the number of trials to find a victim segment
-		when conducting SSR and cleaning operations. The default value
-		is 4096 which covers 8GB block address range.
+Description:
+		 Controls the number of trials to find a victim segment.
 
 What:		/sys/fs/f2fs/<disk>/migration_granularity
 Date:		October 2018
 Contact:	"Chao Yu" <yuchao0@huawei.com>
-Description:	Controls migration granularity of garbage collection on large
-		section, it can let GC move partial segment{s} of one section
-		in one GC cycle, so that dispersing heavy overhead GC to
-		multiple lightweight one.
+Description:
+		 Controls migration granularity of garbage collection on large
+		 section, it can let GC move partial segment{s} of one section
+		 in one GC cycle, so that dispersing heavy overhead GC to
+		 multiple lightweight one.
 
 What:		/sys/fs/f2fs/<disk>/dir_level
 Date:		March 2014
 Contact:	"Jaegeuk Kim" <jaegeuk.kim@samsung.com>
-Description:	Controls the directory level for large directory. If a
-		directory has a number of files, it can reduce the file lookup
-		latency by increasing this dir_level value. Otherwise, it
-		needs to decrease this value to reduce the space overhead.
-		The default value is 0.
+Description:
+		 Controls the directory level for large directory.
 
 What:		/sys/fs/f2fs/<disk>/ram_thresh
 Date:		March 2014
 Contact:	"Jaegeuk Kim" <jaegeuk.kim@samsung.com>
-Description:	Controls the memory footprint used by free nids and cached
-		nat entries. By default, 1 is set, which indicates
-		10 MB / 1 GB RAM.
+Description:
+		 Controls the memory footprint used by f2fs.
 
 What:		/sys/fs/f2fs/<disk>/batched_trim_sections
 Date:		February 2015
 Contact:	"Jaegeuk Kim" <jaegeuk@kernel.org>
-Description:	Controls the trimming rate in batch mode.
-		<deprecated>
+Description:
+		 Controls the trimming rate in batch mode.
+		 <deprecated>
 
 What:		/sys/fs/f2fs/<disk>/cp_interval
 Date:		October 2015
 Contact:	"Jaegeuk Kim" <jaegeuk@kernel.org>
-Description:	Controls the checkpoint timing, set to 60 seconds by default.
+Description:
+		 Controls the checkpoint timing.
 
 What:		/sys/fs/f2fs/<disk>/idle_interval
 Date:		January 2016
 Contact:	"Jaegeuk Kim" <jaegeuk@kernel.org>
-Description:	Controls the idle timing of system, if there is no FS operation
-		during given interval.
-		Set to 5 seconds by default.
+Description:
+		 Controls the idle timing for all paths other than
+		 discard and gc path.
 
 What:		/sys/fs/f2fs/<disk>/discard_idle_interval
 Date:		September 2018
 Contact:	"Chao Yu" <yuchao0@huawei.com>
 Contact:	"Sahitya Tummala" <stummala@codeaurora.org>
-Description:	Controls the idle timing of discard thread given
-		this time interval.
-		Default is 5 secs.
+Description:
+		 Controls the idle timing for discard path.
 
 What:		/sys/fs/f2fs/<disk>/gc_idle_interval
 Date:		September 2018
 Contact:	"Chao Yu" <yuchao0@huawei.com>
 Contact:	"Sahitya Tummala" <stummala@codeaurora.org>
-Description:    Controls the idle timing for gc path. Set to 5 seconds by default.
+Description:
+		 Controls the idle timing for gc path.
 
 What:		/sys/fs/f2fs/<disk>/iostat_enable
 Date:		August 2017
 Contact:	"Chao Yu" <yuchao0@huawei.com>
-Description:	Controls to enable/disable IO stat.
+Description:
+		 Controls to enable/disable IO stat.
 
 What:		/sys/fs/f2fs/<disk>/ra_nid_pages
 Date:		October 2015
 Contact:	"Chao Yu" <chao2.yu@samsung.com>
-Description:	Controls the count of nid pages to be readaheaded.
-		When building free nids, F2FS reads NAT blocks ahead for
-		speed up. Default is 0.
+Description:
+		 Controls the count of nid pages to be readaheaded.
 
 What:		/sys/fs/f2fs/<disk>/dirty_nats_ratio
 Date:		January 2016
 Contact:	"Chao Yu" <chao2.yu@samsung.com>
-Description:	Controls dirty nat entries ratio threshold, if current
-		ratio exceeds configured threshold, checkpoint will
-		be triggered for flushing dirty nat entries.
+Description:
+		 Controls dirty nat entries ratio threshold, if current
+		 ratio exceeds configured threshold, checkpoint will
+		 be triggered for flushing dirty nat entries.
 
 What:		/sys/fs/f2fs/<disk>/lifetime_write_kbytes
 Date:		January 2016
 Contact:	"Shuoran Liu" <liushuoran@huawei.com>
-Description:	Shows total written kbytes issued to disk.
+Description:
+		 Shows total written kbytes issued to disk.
 
 What:		/sys/fs/f2fs/<disk>/features
 Date:		July 2017
 Contact:	"Jaegeuk Kim" <jaegeuk@kernel.org>
-Description:	Shows all enabled features in current device.
+Description:
+		 Shows all enabled features in current device.
 
 What:		/sys/fs/f2fs/<disk>/inject_rate
 Date:		May 2016
 Contact:	"Sheng Yong" <shengyong1@huawei.com>
-Description:	Controls the injection rate of arbitrary faults.
+Description:
+		 Controls the injection rate.
 
 What:		/sys/fs/f2fs/<disk>/inject_type
 Date:		May 2016
 Contact:	"Sheng Yong" <shengyong1@huawei.com>
-Description:	Controls the injection type of arbitrary faults.
-
-What:		/sys/fs/f2fs/<disk>/dirty_segments
-Date:		October 2017
-Contact:	"Jaegeuk Kim" <jaegeuk@kernel.org>
-Description:	Shows the number of dirty segments.
+Description:
+		 Controls the injection type.
 
 What:		/sys/fs/f2fs/<disk>/reserved_blocks
 Date:		June 2017
 Contact:	"Chao Yu" <yuchao0@huawei.com>
-Description:	Controls target reserved blocks in system, the threshold
-		is soft, it could exceed current available user space.
+Description:
+		 Controls target reserved blocks in system, the threshold
+		 is soft, it could exceed current available user space.
 
 What:		/sys/fs/f2fs/<disk>/current_reserved_blocks
 Date:		October 2017
 Contact:	"Yunlong Song" <yunlong.song@huawei.com>
 Contact:	"Chao Yu" <yuchao0@huawei.com>
-Description:	Shows current reserved blocks in system, it may be temporarily
-		smaller than target_reserved_blocks, but will gradually
-		increase to target_reserved_blocks when more free blocks are
-		freed by user later.
+Description:
+		 Shows current reserved blocks in system, it may be temporarily
+		 smaller than target_reserved_blocks, but will gradually
+		 increase to target_reserved_blocks when more free blocks are
+		 freed by user later.
 
 What:		/sys/fs/f2fs/<disk>/gc_urgent
 Date:		August 2017
 Contact:	"Jaegeuk Kim" <jaegeuk@kernel.org>
-Description:	Do background GC agressively when set. When gc_urgent = 1,
-		background thread starts to do GC by given gc_urgent_sleep_time
-		interval. It is set to 0 by default.
+Description:
+		 Do background GC agressively
 
 What:		/sys/fs/f2fs/<disk>/gc_urgent_sleep_time
 Date:		August 2017
 Contact:	"Jaegeuk Kim" <jaegeuk@kernel.org>
-Description:	Controls sleep time of GC urgent mode. Set to 500ms by default.
+Description:
+		 Controls sleep time of GC urgent mode
 
 What:		/sys/fs/f2fs/<disk>/readdir_ra
 Date:		November 2017
 Contact:	"Sheng Yong" <shengyong1@huawei.com>
-Description:	Controls readahead inode block in readdir. Enabled by default.
-
-What:		/sys/fs/f2fs/<disk>/gc_pin_file_thresh
-Date:		January 2018
-Contact:	Jaegeuk Kim <jaegeuk@kernel.org>
-Description:	This indicates how many GC can be failed for the pinned
-		file. If it exceeds this, F2FS doesn't guarantee its pinning
-		state. 2048 trials is set by default.
+Description:
+		 Controls readahead inode block in readdir.
 
 What:		/sys/fs/f2fs/<disk>/extension_list
 Date:		Feburary 2018
 Contact:	"Chao Yu" <yuchao0@huawei.com>
-Description:	Used to control configure extension list:
-		- Query: cat /sys/fs/f2fs/<disk>/extension_list
-		- Add: echo '[h/c]extension' > /sys/fs/f2fs/<disk>/extension_list
-		- Del: echo '[h/c]!extension' > /sys/fs/f2fs/<disk>/extension_list
-		- [h] means add/del hot file extension
-		- [c] means add/del cold file extension
+Description:
+		 Used to control configure extension list:
+		 - Query: cat /sys/fs/f2fs/<disk>/extension_list
+		 - Add: echo '[h/c]extension' > /sys/fs/f2fs/<disk>/extension_list
+		 - Del: echo '[h/c]!extension' > /sys/fs/f2fs/<disk>/extension_list
+		 - [h] means add/del hot file extension
+		 - [c] means add/del cold file extension
 
 What:		/sys/fs/f2fs/<disk>/unusable
 Date		April 2019
 Contact:	"Daniel Rosenberg" <drosen@google.com>
-Description:	If checkpoint=disable, it displays the number of blocks that
-		are unusable.
-		If checkpoint=enable it displays the enumber of blocks that
-		would be unusable if checkpoint=disable were to be set.
-
-What:		/sys/fs/f2fs/<disk>/encoding
-Date		July 2019
-Contact:	"Daniel Rosenberg" <drosen@google.com>
-Description:	Displays name and version of the encoding set for the filesystem.
-		If no encoding is set, displays (none)
-
-What:		/sys/fs/f2fs/<disk>/free_segments
-Date:		September 2019
-Contact:	"Hridya Valsaraju" <hridya@google.com>
-Description:	Number of free segments in disk.
-
-What:		/sys/fs/f2fs/<disk>/cp_foreground_calls
-Date:		September 2019
-Contact:	"Hridya Valsaraju" <hridya@google.com>
-Description:	Number of checkpoint operations performed on demand. Available when
-		CONFIG_F2FS_STAT_FS=y.
-
-What:		/sys/fs/f2fs/<disk>/cp_background_calls
-Date:		September 2019
-Contact:	"Hridya Valsaraju" <hridya@google.com>
-Description:	Number of checkpoint operations performed in the background to
-		free segments. Available when CONFIG_F2FS_STAT_FS=y.
-
-What:		/sys/fs/f2fs/<disk>/gc_foreground_calls
-Date:		September 2019
-Contact:	"Hridya Valsaraju" <hridya@google.com>
-Description:	Number of garbage collection operations performed on demand.
-		Available when CONFIG_F2FS_STAT_FS=y.
-
-What:		/sys/fs/f2fs/<disk>/gc_background_calls
-Date:		September 2019
-Contact:	"Hridya Valsaraju" <hridya@google.com>
-Description:	Number of garbage collection operations triggered in background.
-		Available when CONFIG_F2FS_STAT_FS=y.
-
-What:		/sys/fs/f2fs/<disk>/moved_blocks_foreground
-Date:		September 2019
-Contact:	"Hridya Valsaraju" <hridya@google.com>
-Description:	Number of blocks moved by garbage collection in foreground.
-		Available when CONFIG_F2FS_STAT_FS=y.
-
-What:		/sys/fs/f2fs/<disk>/moved_blocks_background
-Date:		September 2019
-Contact:	"Hridya Valsaraju" <hridya@google.com>
-Description:	Number of blocks moved by garbage collection in background.
-		Available when CONFIG_F2FS_STAT_FS=y.
-
-What:		/sys/fs/f2fs/<disk>/avg_vblocks
-Date:		September 2019
-Contact:	"Hridya Valsaraju" <hridya@google.com>
-Description:	Average number of valid blocks.
-		Available when CONFIG_F2FS_STAT_FS=y.
+Description:
+		If checkpoint=disable, it displays the number of blocks that are unusable.
+                If checkpoint=enable it displays the enumber of blocks that would be unusable
+                if checkpoint=disable were to be set.

Documentation/ABI/testing/sysfs-kernel-btf

@@ -1,17 +0,0 @@
-What:		/sys/kernel/btf
-Date:		Aug 2019
-KernelVersion:	5.5
-Contact:	bpf@vger.kernel.org
-Description:
-		Contains BTF type information and related data for kernel and
-		kernel modules.
-
-What:		/sys/kernel/btf/vmlinux
-Date:		Aug 2019
-KernelVersion:	5.5
-Contact:	bpf@vger.kernel.org
-Description:
-		Read-only binary attribute exposing kernel's own BTF type
-		information with description of all internal kernel types. See
-		Documentation/bpf/btf.rst for detailed description of format
-		itself.

Documentation/ABI/testing/sysfs-kernel-slab

@@ -429,15 +429,10 @@ KernelVersion:	2.6.22
 Contact:	Pekka Enberg <penberg@cs.helsinki.fi>,
 		Christoph Lameter <cl@linux-foundation.org>
 Description:
-		The shrink file is used to reclaim unused slab cache
-		memory from a cache.  Empty per-cpu or partial slabs
-		are freed and the partial list is sorted so the slabs
-		with the fewest available objects are used first.
-		It only accepts a value of "1" on write for shrinking
-		the cache. Other input values are considered invalid.
-		Shrinking slab caches might be expensive and can
-		adversely impact other running applications.  So it
-		should be used with care.
+		The shrink file is written when memory should be reclaimed from
+		a cache.  Empty partial slabs are freed and the partial list is
+		sorted so the slabs with the fewest available objects are used
+		first.
 
 What:		/sys/kernel/slab/cache/slab_size
 Date:		May 2007

Documentation/ABI/testing/sysfs-platform-asus-wmi

@@ -46,13 +46,3 @@ Description:
 			* 0 - normal,
 			* 1 - overboost,
 			* 2 - silent
-
-What:		/sys/devices/platform/<platform>/throttle_thermal_policy
-Date:		Dec 2019
-KernelVersion:	5.6
-Contact:	"Leonid Maksymchuk" <leonmaxx@gmail.com>
-Description:
-		Throttle thermal policy mode:
-			* 0 - default,
-			* 1 - overboost,
-			* 2 - silent

Documentation/ABI/testing/sysfs-platform-dfl-fme

@@ -21,220 +21,3 @@ Contact:	Wu Hao <hao.wu@intel.com>
 Description:	Read-only. It returns Bitstream (static FPGA region) meta
 		data, which includes the synthesis date, seed and other
 		information of this static FPGA region.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/cache_size
-Date:		August 2019
-KernelVersion:  5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-only. It returns cache size of this FPGA device.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/fabric_version
-Date:		August 2019
-KernelVersion:  5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-only. It returns fabric version of this FPGA device.
-		Userspace applications need this information to select
-		best data channels per different fabric design.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/socket_id
-Date:		August 2019
-KernelVersion:  5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-only. It returns socket_id to indicate which socket
-		this FPGA belongs to, only valid for integrated solution.
-		User only needs this information, in case standard numa node
-		can't provide correct information.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/errors/pcie0_errors
-Date:		August 2019
-KernelVersion:  5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-Write. Read this file for errors detected on pcie0 link.
-		Write this file to clear errors logged in pcie0_errors. Write
-		fails with -EINVAL if input parsing fails or input error code
-		doesn't match.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/errors/pcie1_errors
-Date:		August 2019
-KernelVersion:  5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-Write. Read this file for errors detected on pcie1 link.
-		Write this file to clear errors logged in pcie1_errors. Write
-		fails with -EINVAL if input parsing fails or input error code
-		doesn't match.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/errors/nonfatal_errors
-Date:		August 2019
-KernelVersion:  5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-only. It returns non-fatal errors detected.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/errors/catfatal_errors
-Date:		August 2019
-KernelVersion:  5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-only. It returns catastrophic and fatal errors detected.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/errors/inject_errors
-Date:		August 2019
-KernelVersion:  5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-Write. Read this file to check errors injected. Write this
-		file to inject errors for testing purpose. Write fails with
-		-EINVAL if input parsing fails or input inject error code isn't
-		supported.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/errors/fme_errors
-Date:		August 2019
-KernelVersion:  5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-Write. Read this file to get errors detected on FME.
-		Write this file to clear errors logged in fme_errors. Write
-		fials with -EINVAL if input parsing fails or input error code
-		doesn't match.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/errors/first_error
-Date:		August 2019
-KernelVersion:  5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-only. Read this file to get the first error detected by
-		hardware.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/errors/next_error
-Date:		August 2019
-KernelVersion:  5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-only. Read this file to get the second error detected by
-		hardware.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/name
-Date:		October 2019
-KernelVersion:	5.5
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-Only. Read this file to get the name of hwmon device, it
-		supports values:
-		    'dfl_fme_thermal' - thermal hwmon device name
-		    'dfl_fme_power'   - power hwmon device name
-
-What:		/sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/temp1_input
-Date:		October 2019
-KernelVersion:	5.5
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-Only. It returns FPGA device temperature in millidegrees
-		Celsius.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/temp1_max
-Date:		October 2019
-KernelVersion:	5.5
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-Only. It returns hardware threshold1 temperature in
-		millidegrees Celsius. If temperature rises at or above this
-		threshold, hardware starts 50% or 90% throttling (see
-		'temp1_max_policy').
-
-What:		/sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/temp1_crit
-Date:		October 2019
-KernelVersion:	5.5
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-Only. It returns hardware threshold2 temperature in
-		millidegrees Celsius. If temperature rises at or above this
-		threshold, hardware starts 100% throttling.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/temp1_emergency
-Date:		October 2019
-KernelVersion:	5.5
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-Only. It returns hardware trip threshold temperature in
-		millidegrees Celsius. If temperature rises at or above this
-		threshold, a fatal event will be triggered to board management
-		controller (BMC) to shutdown FPGA.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/temp1_max_alarm
-Date:		October 2019
-KernelVersion:	5.5
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-only. It returns 1 if temperature is currently at or above
-		hardware threshold1 (see 'temp1_max'), otherwise 0.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/temp1_crit_alarm
-Date:		October 2019
-KernelVersion:	5.5
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-only. It returns 1 if temperature is currently at or above
-		hardware threshold2 (see 'temp1_crit'), otherwise 0.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/temp1_max_policy
-Date:		October 2019
-KernelVersion:	5.5
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-Only. Read this file to get the policy of hardware threshold1
-		(see 'temp1_max'). It only supports two values (policies):
-		    0 - AP2 state (90% throttling)
-		    1 - AP1 state (50% throttling)
-
-What:		/sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_input
-Date:		October 2019
-KernelVersion:	5.5
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-Only. It returns current FPGA power consumption in uW.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_max
-Date:		October 2019
-KernelVersion:	5.5
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-Write. Read this file to get current hardware power
-		threshold1 in uW. If power consumption rises at or above
-		this threshold, hardware starts 50% throttling.
-		Write this file to set current hardware power threshold1 in uW.
-		As hardware only accepts values in Watts, so input value will
-		be round down per Watts (< 1 watts part will be discarded) and
-		clamped within the range from 0 to 127 Watts. Write fails with
-		-EINVAL if input parsing fails.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_crit
-Date:		October 2019
-KernelVersion:	5.5
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-Write. Read this file to get current hardware power
-		threshold2 in uW. If power consumption rises at or above
-		this threshold, hardware starts 90% throttling.
-		Write this file to set current hardware power threshold2 in uW.
-		As hardware only accepts values in Watts, so input value will
-		be round down per Watts (< 1 watts part will be discarded) and
-		clamped within the range from 0 to 127 Watts. Write fails with
-		-EINVAL if input parsing fails.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_max_alarm
-Date:		October 2019
-KernelVersion:	5.5
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-only. It returns 1 if power consumption is currently at or
-		above hardware threshold1 (see 'power1_max'), otherwise 0.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_crit_alarm
-Date:		October 2019
-KernelVersion:	5.5
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-only. It returns 1 if power consumption is currently at or
-		above hardware threshold2 (see 'power1_crit'), otherwise 0.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_xeon_limit
-Date:		October 2019
-KernelVersion:	5.5
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-Only. It returns power limit for XEON in uW.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_fpga_limit
-Date:		October 2019
-KernelVersion:	5.5
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-Only. It returns power limit for FPGA in uW.
-
-What:		/sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_ltr
-Date:		October 2019
-KernelVersion:	5.5
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-only. Read this file to get current Latency Tolerance
-		Reporting (ltr) value. It returns 1 if all Accelerated
-		Function Units (AFUs) can tolerate latency >= 40us for memory
-		access or 0 if any AFU is latency sensitive (< 40us).

Documentation/ABI/testing/sysfs-platform-dfl-port

@@ -14,88 +14,3 @@ Description:	Read-only. User can program different PR bitstreams to FPGA
 		Accelerator Function Unit (AFU) for different functions. It
 		returns uuid which could be used to identify which PR bitstream
 		is programmed in this AFU.
-
-What:		/sys/bus/platform/devices/dfl-port.0/power_state
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-only. It reports the APx (AFU Power) state, different APx
-		means different throttling level. When reading this file, it
-		returns "0" - Normal / "1" - AP1 / "2" - AP2 / "6" - AP6.
-
-What:		/sys/bus/platform/devices/dfl-port.0/ap1_event
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-write. Read this file for AP1 (AFU Power State 1) event.
-		It's used to indicate transient AP1 state. Write 1 to this
-		file to clear AP1 event.
-
-What:		/sys/bus/platform/devices/dfl-port.0/ap2_event
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-write. Read this file for AP2 (AFU Power State 2) event.
-		It's used to indicate transient AP2 state. Write 1 to this
-		file to clear AP2 event.
-
-What:		/sys/bus/platform/devices/dfl-port.0/ltr
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-write. Read or set AFU latency tolerance reporting value.
-		Set ltr to 1 if the AFU can tolerate latency >= 40us or set it
-		to 0 if it is latency sensitive.
-
-What:		/sys/bus/platform/devices/dfl-port.0/userclk_freqcmd
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Write-only. User writes command to this interface to set
-		userclock to AFU.
-
-What:		/sys/bus/platform/devices/dfl-port.0/userclk_freqsts
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-only. Read this file to get the status of issued command
-		to userclck_freqcmd.
-
-What:		/sys/bus/platform/devices/dfl-port.0/userclk_freqcntrcmd
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Write-only. User writes command to this interface to set
-		userclock counter.
-
-What:		/sys/bus/platform/devices/dfl-port.0/userclk_freqcntrsts
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-only. Read this file to get the status of issued command
-		to userclck_freqcntrcmd.
-
-What:		/sys/bus/platform/devices/dfl-port.0/errors/errors
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-Write. Read this file to get errors detected on port and
-		Accelerated Function Unit (AFU). Write error code to this file
-		to clear errors. Write fails with -EINVAL if input parsing
-		fails or input error code doesn't match. Write fails with
-		-EBUSY or -ETIMEDOUT if error can't be cleared as hardware
-		in low power state (-EBUSY) or not respoding (-ETIMEDOUT).
-
-What:		/sys/bus/platform/devices/dfl-port.0/errors/first_error
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-only. Read this file to get the first error detected by
-		hardware.
-
-What:		/sys/bus/platform/devices/dfl-port.0/errors/first_malformed_req
-Date:		August 2019
-KernelVersion:	5.4
-Contact:	Wu Hao <hao.wu@intel.com>
-Description:	Read-only. Read this file to get the first malformed request
-		captured by hardware.

Documentation/ABI/testing/sysfs-platform-mellanox-bootctl

@@ -1,58 +0,0 @@
-What:		/sys/bus/platform/devices/MLNXBF04:00/lifecycle_state
-Date:		Oct 2019
-KernelVersion:	5.5
-Contact:	"Liming Sun <lsun@mellanox.com>"
-Description:
-		The Life-cycle state of the SoC, which could be one of the
-		following values.
-		  Production - Production state and can be updated to secure
-		  GA Secured - Secure chip and not able to change state
-		  GA Non-Secured - Non-Secure chip and not able to change state
-		  RMA - Return Merchandise Authorization
-
-What:		/sys/bus/platform/devices/MLNXBF04:00/post_reset_wdog
-Date:		Oct 2019
-KernelVersion:	5.5
-Contact:	"Liming Sun <lsun@mellanox.com>"
-Description:
-		The watchdog setting in seconds for the next booting. It's used
-		to reboot the chip and recover it to the old state if the new
-		boot partition fails.
-
-What:		/sys/bus/platform/devices/MLNXBF04:00/reset_action
-Date:		Oct 2019
-KernelVersion:	5.5
-Contact:	"Liming Sun <lsun@mellanox.com>"
-Description:
-		The source of the boot stream for the next reset. It could be
-		one of the following values.
-		  external - boot from external source (USB or PCIe)
-		  emmc - boot from the onchip eMMC
-		  emmc_legacy - boot from the onchip eMMC in legacy (slow) mode
-
-What:		/sys/bus/platform/devices/MLNXBF04:00/second_reset_action
-Date:		Oct 2019
-KernelVersion:	5.5
-Contact:	"Liming Sun <lsun@mellanox.com>"
-Description:
-		Update the source of the boot stream after next reset. It could
-		be one of the following values and will be applied after next
-		reset.
-		  external - boot from external source (USB or PCIe)
-		  emmc - boot from the onchip eMMC
-		  emmc_legacy - boot from the onchip eMMC in legacy (slow) mode
-		  swap_emmc - swap the primary / secondary boot partition
-		  none - cancel the action
-
-What:		/sys/bus/platform/devices/MLNXBF04:00/secure_boot_fuse_state
-Date:		Oct 2019
-KernelVersion:	5.5
-Contact:	"Liming Sun <lsun@mellanox.com>"
-Description:
-		The state of eFuse versions with the following values.
-		  InUse - burnt, valid and currently in use
-		  Used - burnt and valid
-		  Free - not burnt and free to use
-		  Skipped - not burnt but not free (skipped)
-		  Wasted - burnt and invalid
-		  Invalid - not burnt but marked as valid (error state).

Documentation/ABI/testing/sysfs-platform-wilco-ec

@@ -31,23 +31,6 @@ Description:
                Output will a version string be similar to the example below:
                08B6
 
-What:          /sys/bus/platform/devices/GOOG000C\:00/usb_charge
-Date:          October 2019
-KernelVersion: 5.5
-Description:
-               Control the USB PowerShare Policy. USB PowerShare is a policy
-               which affects charging via the special USB PowerShare port
-               (marked with a small lightning bolt or battery icon) when in
-               low power states:
-               - In S0, the port will always provide power.
-               - In S0ix, if usb_charge is enabled, then power will be
-                 supplied to the port when on AC or if battery is > 50%.
-                 Else no power is supplied.
-               - In S5, if usb_charge is enabled, then power will be supplied
-                 to the port when on AC. Else no power is supplied.
-
-               Input should be either "0" or "1".
-
 What:          /sys/bus/platform/devices/GOOG000C\:00/version
 Date:          May 2019
 KernelVersion: 5.3

Documentation/ABI/testing/sysfs-power

@@ -301,122 +301,3 @@ Description:
 
 		Using this sysfs file will override any values that were
 		set using the kernel command line for disk offset.
-
-What:		/sys/power/suspend_stats
-Date:		July 2019
-Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
-Description:
-		The /sys/power/suspend_stats directory contains suspend related
-		statistics.
-
-What:		/sys/power/suspend_stats/success
-Date:		July 2019
-Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
-Description:
-		The /sys/power/suspend_stats/success file contains the number
-		of times entering system sleep state succeeded.
-
-What:		/sys/power/suspend_stats/fail
-Date:		July 2019
-Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
-Description:
-		The /sys/power/suspend_stats/fail file contains the number
-		of times entering system sleep state failed.
-
-What:		/sys/power/suspend_stats/failed_freeze
-Date:		July 2019
-Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
-Description:
-		The /sys/power/suspend_stats/failed_freeze file contains the
-		number of times freezing processes failed.
-
-What:		/sys/power/suspend_stats/failed_prepare
-Date:		July 2019
-Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
-Description:
-		The /sys/power/suspend_stats/failed_prepare file contains the
-		number of times preparing all non-sysdev devices for
-		a system PM transition failed.
-
-What:		/sys/power/suspend_stats/failed_resume
-Date:		July 2019
-Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
-Description:
-		The /sys/power/suspend_stats/failed_resume file contains the
-		number of times executing "resume" callbacks of
-		non-sysdev devices failed.
-
-What:		/sys/power/suspend_stats/failed_resume_early
-Date:		July 2019
-Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
-Description:
-		The /sys/power/suspend_stats/failed_resume_early file contains
-		the number of times executing "early resume" callbacks
-		of devices failed.
-
-What:		/sys/power/suspend_stats/failed_resume_noirq
-Date:		July 2019
-Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
-Description:
-		The /sys/power/suspend_stats/failed_resume_noirq file contains
-		the number of times executing "noirq resume" callbacks
-		of devices failed.
-
-What:		/sys/power/suspend_stats/failed_suspend
-Date:		July 2019
-Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
-Description:
-		The /sys/power/suspend_stats/failed_suspend file contains
-		the number of times executing "suspend" callbacks
-		of all non-sysdev devices failed.
-
-What:		/sys/power/suspend_stats/failed_suspend_late
-Date:		July 2019
-Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
-Description:
-		The /sys/power/suspend_stats/failed_suspend_late file contains
-		the number of times executing "late suspend" callbacks
-		of all devices failed.
-
-What:		/sys/power/suspend_stats/failed_suspend_noirq
-Date:		July 2019
-Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
-Description:
-		The /sys/power/suspend_stats/failed_suspend_noirq file contains
-		the number of times executing "noirq suspend" callbacks
-		of all devices failed.
-
-What:		/sys/power/suspend_stats/last_failed_dev
-Date:		July 2019
-Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
-Description:
-		The /sys/power/suspend_stats/last_failed_dev file contains
-		the last device for which a suspend/resume callback failed.
-
-What:		/sys/power/suspend_stats/last_failed_errno
-Date:		July 2019
-Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
-Description:
-		The /sys/power/suspend_stats/last_failed_errno file contains
-		the errno of the last failed attempt at entering
-		system sleep state.
-
-What:		/sys/power/suspend_stats/last_failed_step
-Date:		July 2019
-Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
-Description:
-		The /sys/power/suspend_stats/last_failed_step file contains
-		the last failed step in the suspend/resume path.
-
-What:		/sys/power/sync_on_suspend
-Date:		October 2019
-Contact:	Jonas Meurer <jonas@freesources.org>
-Description:
-		This file controls whether or not the kernel will sync()
-		filesystems during system suspend (after freezing user space
-		and before suspending devices).
-
-		Writing a "1" to this file enables the sync() and writing a "0"
-		disables it.  Reads from the file return the current value.
-		The default is "1" if the build-time "SUSPEND_SKIP_SYNC" config
-		flag is unset, or "0" otherwise.

Documentation/ABI/testing/sysfs-secvar

@@ -1,46 +0,0 @@
-What:		/sys/firmware/secvar
-Date:		August 2019
-Contact:	Nayna Jain <nayna@linux.ibm.com>
-Description:	This directory is created if the POWER firmware supports OS
-		secureboot, thereby secure variables. It exposes interface
-		for reading/writing the secure variables
-
-What:		/sys/firmware/secvar/vars
-Date:		August 2019
-Contact:	Nayna Jain <nayna@linux.ibm.com>
-Description:	This directory lists all the secure variables that are supported
-		by the firmware.
-
-What:		/sys/firmware/secvar/format
-Date:		August 2019
-Contact:	Nayna Jain <nayna@linux.ibm.com>
-Description:	A string indicating which backend is in use by the firmware.
-		This determines the format of the variable and the accepted
-		format of variable updates.
-
-What:		/sys/firmware/secvar/vars/<variable name>
-Date:		August 2019
-Contact:	Nayna Jain <nayna@linux.ibm.com>
-Description:	Each secure variable is represented as a directory named as
-		<variable_name>. The variable name is unique and is in ASCII
-		representation. The data and size can be determined by reading
-		their respective attribute files.
-
-What:		/sys/firmware/secvar/vars/<variable_name>/size
-Date:		August 2019
-Contact:	Nayna Jain <nayna@linux.ibm.com>
-Description:	An integer representation of the size of the content of the
-		variable. In other words, it represents the size of the data.
-
-What:		/sys/firmware/secvar/vars/<variable_name>/data
-Date:		August 2019
-Contact:	Nayna Jain h<nayna@linux.ibm.com>
-Description:	A read-only file containing the value of the variable. The size
-		of the file represents the maximum size of the variable data.
-
-What:		/sys/firmware/secvar/vars/<variable_name>/update
-Date:		August 2019
-Contact:	Nayna Jain <nayna@linux.ibm.com>
-Description:	A write-only file that is used to submit the new value for the
-		variable. The size of the file represents the maximum size of
-		the variable data that can be written.

Documentation/ABI/testing/usb-charger-uevent

@@ -1,46 +0,0 @@
-What:		Raise a uevent when a USB charger is inserted or removed
-Date:		2020-01-14
-KernelVersion:	5.6
-Contact:	linux-usb@vger.kernel.org
-Description:	There are two USB charger states:
-		USB_CHARGER_ABSENT
-		USB_CHARGER_PRESENT
-		There are five USB charger types:
-		USB_CHARGER_UNKNOWN_TYPE: Charger type is unknown
-		USB_CHARGER_SDP_TYPE: Standard Downstream Port
-		USB_CHARGER_CDP_TYPE: Charging Downstream Port
-		USB_CHARGER_DCP_TYPE: Dedicated Charging Port
-		USB_CHARGER_ACA_TYPE: Accessory Charging Adapter
-		https://www.usb.org/document-library/battery-charging-v12-spec-and-adopters-agreement
-
-		Here are two examples taken using udevadm monitor -p when
-		USB charger is online:
-		UDEV  change   /devices/soc0/usbphynop1 (platform)
-		ACTION=change
-		DEVPATH=/devices/soc0/usbphynop1
-		DRIVER=usb_phy_generic
-		MODALIAS=of:Nusbphynop1T(null)Cusb-nop-xceiv
-		OF_COMPATIBLE_0=usb-nop-xceiv
-		OF_COMPATIBLE_N=1
-		OF_FULLNAME=/usbphynop1
-		OF_NAME=usbphynop1
-		SEQNUM=2493
-		SUBSYSTEM=platform
-		USB_CHARGER_STATE=USB_CHARGER_PRESENT
-		USB_CHARGER_TYPE=USB_CHARGER_SDP_TYPE
-		USEC_INITIALIZED=227422826
-
-		USB charger is offline:
-		KERNEL change   /devices/soc0/usbphynop1 (platform)
-		ACTION=change
-		DEVPATH=/devices/soc0/usbphynop1
-		DRIVER=usb_phy_generic
-		MODALIAS=of:Nusbphynop1T(null)Cusb-nop-xceiv
-		OF_COMPATIBLE_0=usb-nop-xceiv
-		OF_COMPATIBLE_N=1
-		OF_FULLNAME=/usbphynop1
-		OF_NAME=usbphynop1
-		SEQNUM=2494
-		SUBSYSTEM=platform
-		USB_CHARGER_STATE=USB_CHARGER_ABSENT
-		USB_CHARGER_TYPE=USB_CHARGER_UNKNOWN_TYPE

Documentation/DMA-API.txt

@@ -204,14 +204,6 @@ Returns the maximum size of a mapping for the device. The size parameter
 of the mapping functions like dma_map_single(), dma_map_page() and
 others should not be larger than the returned value.
 
-::
-
-	unsigned long
-	dma_get_merge_boundary(struct device *dev);
-
-Returns the DMA merge boundary. If the device cannot merge any the DMA address
-segments, the function returns 0.
-
 Part Id - Streaming DMA mappings
 --------------------------------
 
@@ -603,6 +595,17 @@ For reasons of efficiency, most platforms choose to track the declared
 region only at the granularity of a page.  For smaller allocations,
 you should use the dma_pool() API.
 
+::
+
+	void
+	dma_release_declared_memory(struct device *dev)
+
+Remove the memory region previously declared from the system.  This
+API performs *no* in-use checking for this region and will return
+unconditionally having removed all the required structures.  It is the
+driver's job to ensure that no parts of this memory region are
+currently in use.
+
 Part III - Debug drivers use of the DMA-API
 -------------------------------------------
 

Documentation/DMA-attributes.txt

@@ -5,6 +5,24 @@ DMA attributes
 This document describes the semantics of the DMA attributes that are
 defined in linux/dma-mapping.h.
 
+DMA_ATTR_WRITE_BARRIER
+----------------------
+
+DMA_ATTR_WRITE_BARRIER is a (write) barrier attribute for DMA.  DMA
+to a memory region with the DMA_ATTR_WRITE_BARRIER attribute forces
+all pending DMA writes to complete, and thus provides a mechanism to
+strictly order DMA from a device across all intervening busses and
+bridges.  This barrier is not specific to a particular type of
+interconnect, it applies to the system as a whole, and so its
+implementation must account for the idiosyncrasies of the system all
+the way from the DMA device to memory.
+
+As an example of a situation where DMA_ATTR_WRITE_BARRIER would be
+useful, suppose that a device does a DMA write to indicate that data is
+ready and available in memory.  The DMA of the "completion indication"
+could race with data DMA.  Mapping the memory used for completion
+indications with DMA_ATTR_WRITE_BARRIER would prevent the race.
+
 DMA_ATTR_WEAK_ORDERING
 ----------------------
 

Documentation/Makefile

@@ -13,7 +13,7 @@ endif
 SPHINXBUILD   = sphinx-build
 SPHINXOPTS    =
 SPHINXDIRS    = .
-_SPHINXDIRS   = $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst))
+_SPHINXDIRS   = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py))
 SPHINX_CONF   = conf.py
 PAPER         =
 BUILDDIR      = $(obj)/output
@@ -33,6 +33,8 @@ ifeq ($(HAVE_SPHINX),0)
 
 else # HAVE_SPHINX
 
+export SPHINXOPTS = $(shell perl -e 'open IN,"sphinx-build --version 2>&1 |"; while (<IN>) { if (m/([\d\.]+)/) { print "-jauto" 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)
@@ -65,8 +67,6 @@ 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) \
 	-b $2 \
 	-c $(abspath $(srctree)/$(src)) \
@@ -128,10 +128,8 @@ dochelp:
 	@echo  '  pdfdocs         - PDF'
 	@echo  '  epubdocs        - EPUB'
 	@echo  '  xmldocs         - XML'
-	@echo  '  linkcheckdocs   - check for broken external links'
-	@echo  '                    (will connect to external hosts)'
-	@echo  '  refcheckdocs    - check for references to non-existing files under'
-	@echo  '                    Documentation'
+	@echo  '  linkcheckdocs   - check for broken external links (will connect to external hosts)'
+	@echo  '  refcheckdocs    - check for references to non-existing files under Documentation'
 	@echo  '  cleandocs       - clean all generated files'
 	@echo
 	@echo  '  make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'

Documentation/PCI/msi-howto.rst

@@ -283,5 +283,5 @@ or disabled (0).  If 0 is found in any of the msi_bus files belonging
 to bridges between the PCI root and the device, MSIs are disabled.
 
 It is also worth checking the device driver to see whether it supports MSIs.
-For example, it may contain calls to pci_alloc_irq_vectors() with the
+For example, it may contain calls to pci_irq_alloc_vectors() with the
 PCI_IRQ_MSI or PCI_IRQ_MSIX flags.

Documentation/PCI/pci-error-recovery.rst

@@ -421,6 +421,7 @@ That is, the recovery API only requires that:
    - drivers/net/ixgbe
    - drivers/net/cxgb3
    - drivers/net/s2io.c
+   - drivers/net/qlge
 
 The End
 -------

Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.html

@@ -0,0 +1,668 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+        "http://www.w3.org/TR/html4/loose.dtd">
+        <html>
+        <head><title>A Tour Through TREE_RCU's Expedited Grace Periods</title>
+        <meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
+
+<h2>Introduction</h2>
+
+This document describes RCU's expedited grace periods.
+Unlike RCU's normal grace periods, which accept long latencies to attain
+high efficiency and minimal disturbance, expedited grace periods accept
+lower efficiency and significant disturbance to attain shorter latencies.
+
+<p>
+There are two flavors of RCU (RCU-preempt and RCU-sched), with an earlier
+third RCU-bh flavor having been implemented in terms of the other two.
+Each of the two implementations is covered in its own section.
+
+<ol>
+<li>	<a href="#Expedited Grace Period Design">
+	Expedited Grace Period Design</a>
+<li>	<a href="#RCU-preempt Expedited Grace Periods">
+	RCU-preempt Expedited Grace Periods</a>
+<li>	<a href="#RCU-sched Expedited Grace Periods">
+	RCU-sched Expedited Grace Periods</a>
+<li>	<a href="#Expedited Grace Period and CPU Hotplug">
+	Expedited Grace Period and CPU Hotplug</a>
+<li>	<a href="#Expedited Grace Period Refinements">
+	Expedited Grace Period Refinements</a>
+</ol>
+
+<h2><a name="Expedited Grace Period Design">
+Expedited Grace Period Design</a></h2>
+
+<p>
+The expedited RCU grace periods cannot be accused of being subtle,
+given that they for all intents and purposes hammer every CPU that
+has not yet provided a quiescent state for the current expedited
+grace period.
+The one saving grace is that the hammer has grown a bit smaller
+over time:  The old call to <tt>try_stop_cpus()</tt> has been
+replaced with a set of calls to <tt>smp_call_function_single()</tt>,
+each of which results in an IPI to the target CPU.
+The corresponding handler function checks the CPU's state, motivating
+a faster quiescent state where possible, and triggering a report
+of that quiescent state.
+As always for RCU, once everything has spent some time in a quiescent
+state, the expedited grace period has completed.
+
+<p>
+The details of the <tt>smp_call_function_single()</tt> handler's
+operation depend on the RCU flavor, as described in the following
+sections.
+
+<h2><a name="RCU-preempt Expedited Grace Periods">
+RCU-preempt Expedited Grace Periods</a></h2>
+
+<p>
+<tt>CONFIG_PREEMPT=y</tt> kernels implement RCU-preempt.
+The overall flow of the handling of a given CPU by an RCU-preempt
+expedited grace period is shown in the following diagram:
+
+<p><img src="ExpRCUFlow.svg" alt="ExpRCUFlow.svg" width="55%">
+
+<p>
+The solid arrows denote direct action, for example, a function call.
+The dotted arrows denote indirect action, for example, an IPI
+or a state that is reached after some time.
+
+<p>
+If a given CPU is offline or idle, <tt>synchronize_rcu_expedited()</tt>
+will ignore it because idle and offline CPUs are already residing
+in quiescent states.
+Otherwise, the expedited grace period will use
+<tt>smp_call_function_single()</tt> to send the CPU an IPI, which
+is handled by <tt>rcu_exp_handler()</tt>.
+
+<p>
+However, because this is preemptible RCU, <tt>rcu_exp_handler()</tt>
+can check to see if the CPU is currently running in an RCU read-side
+critical section.
+If not, the handler can immediately report a quiescent state.
+Otherwise, it sets flags so that the outermost <tt>rcu_read_unlock()</tt>
+invocation will provide the needed quiescent-state report.
+This flag-setting avoids the previous forced preemption of all
+CPUs that might have RCU read-side critical sections.
+In addition, this flag-setting is done so as to avoid increasing
+the overhead of the common-case fastpath through the scheduler.
+
+<p>
+Again because this is preemptible RCU, an RCU read-side critical section
+can be preempted.
+When that happens, RCU will enqueue the task, which will the continue to
+block the current expedited grace period until it resumes and finds its
+outermost <tt>rcu_read_unlock()</tt>.
+The CPU will report a quiescent state just after enqueuing the task because
+the CPU is no longer blocking the grace period.
+It is instead the preempted task doing the blocking.
+The list of blocked tasks is managed by <tt>rcu_preempt_ctxt_queue()</tt>,
+which is called from <tt>rcu_preempt_note_context_switch()</tt>, which
+in turn is called from <tt>rcu_note_context_switch()</tt>, which in
+turn is called from the scheduler.
+
+<table>
+<tr><th>&nbsp;</th></tr>
+<tr><th align="left">Quick Quiz:</th></tr>
+<tr><td>
+	Why not just have the expedited grace period check the
+	state of all the CPUs?
+	After all, that would avoid all those real-time-unfriendly IPIs.
+</td></tr>
+<tr><th align="left">Answer:</th></tr>
+<tr><td bgcolor="#ffffff"><font color="ffffff">
+	Because we want the RCU read-side critical sections to run fast,
+	which means no memory barriers.
+	Therefore, it is not possible to safely check the state from some
+	other CPU.
+	And even if it was possible to safely check the state, it would
+	still be necessary to IPI the CPU to safely interact with the
+	upcoming <tt>rcu_read_unlock()</tt> invocation, which means that
+	the remote state testing would not help the worst-case
+	latency that real-time applications care about.
+
+	<p><font color="ffffff">One way to prevent your real-time
+	application from getting hit with these IPIs is to
+	build your kernel with <tt>CONFIG_NO_HZ_FULL=y</tt>.
+	RCU would then perceive the CPU running your application
+	as being idle, and it would be able to safely detect that
+	state without needing to IPI the CPU.
+</font></td></tr>
+<tr><td>&nbsp;</td></tr>
+</table>
+
+<p>
+Please note that this is just the overall flow:
+Additional complications can arise due to races with CPUs going idle
+or offline, among other things.
+
+<h2><a name="RCU-sched Expedited Grace Periods">
+RCU-sched Expedited Grace Periods</a></h2>
+
+<p>
+<tt>CONFIG_PREEMPT=n</tt> kernels implement RCU-sched.
+The overall flow of the handling of a given CPU by an RCU-sched
+expedited grace period is shown in the following diagram:
+
+<p><img src="ExpSchedFlow.svg" alt="ExpSchedFlow.svg" width="55%">
+
+<p>
+As with RCU-preempt, RCU-sched's
+<tt>synchronize_rcu_expedited()</tt> ignores offline and
+idle CPUs, again because they are in remotely detectable
+quiescent states.
+However, because the
+<tt>rcu_read_lock_sched()</tt> and <tt>rcu_read_unlock_sched()</tt>
+leave no trace of their invocation, in general it is not possible to tell
+whether or not the current CPU is in an RCU read-side critical section.
+The best that RCU-sched's <tt>rcu_exp_handler()</tt> can do is to check
+for idle, on the off-chance that the CPU went idle while the IPI
+was in flight.
+If the CPU is idle, then <tt>rcu_exp_handler()</tt> reports
+the quiescent state.
+
+<p> Otherwise, the handler forces a future context switch by setting the
+NEED_RESCHED flag of the current task's thread flag and the CPU preempt
+counter.
+At the time of the context switch, the CPU reports the quiescent state.
+Should the CPU go offline first, it will report the quiescent state
+at that time.
+
+<h2><a name="Expedited Grace Period and CPU Hotplug">
+Expedited Grace Period and CPU Hotplug</a></h2>
+
+<p>
+The expedited nature of expedited grace periods require a much tighter
+interaction with CPU hotplug operations than is required for normal
+grace periods.
+In addition, attempting to IPI offline CPUs will result in splats, but
+failing to IPI online CPUs can result in too-short grace periods.
+Neither option is acceptable in production kernels.
+
+<p>
+The interaction between expedited grace periods and CPU hotplug operations
+is carried out at several levels:
+
+<ol>
+<li>	The number of CPUs that have ever been online is tracked
+	by the <tt>rcu_state</tt> structure's <tt>-&gt;ncpus</tt>
+	field.
+	The <tt>rcu_state</tt> structure's <tt>-&gt;ncpus_snap</tt>
+	field tracks the number of CPUs that have ever been online
+	at the beginning of an RCU expedited grace period.
+	Note that this number never decreases, at least in the absence
+	of a time machine.
+<li>	The identities of the CPUs that have ever been online is
+	tracked by the <tt>rcu_node</tt> structure's
+	<tt>-&gt;expmaskinitnext</tt> field.
+	The <tt>rcu_node</tt> structure's <tt>-&gt;expmaskinit</tt>
+	field tracks the identities of the CPUs that were online
+	at least once at the beginning of the most recent RCU
+	expedited grace period.
+	The <tt>rcu_state</tt> structure's <tt>-&gt;ncpus</tt> and
+	<tt>-&gt;ncpus_snap</tt> fields are used to detect when
+	new CPUs have come online for the first time, that is,
+	when the <tt>rcu_node</tt> structure's <tt>-&gt;expmaskinitnext</tt>
+	field has changed since the beginning of the last RCU
+	expedited grace period, which triggers an update of each
+	<tt>rcu_node</tt> structure's <tt>-&gt;expmaskinit</tt>
+	field from its <tt>-&gt;expmaskinitnext</tt> field.
+<li>	Each <tt>rcu_node</tt> structure's <tt>-&gt;expmaskinit</tt>
+	field is used to initialize that structure's
+	<tt>-&gt;expmask</tt> at the beginning of each RCU
+	expedited grace period.
+	This means that only those CPUs that have been online at least
+	once will be considered for a given grace period.
+<li>	Any CPU that goes offline will clear its bit in its leaf
+	<tt>rcu_node</tt> structure's <tt>-&gt;qsmaskinitnext</tt>
+	field, so any CPU with that bit clear can safely be ignored.
+	However, it is possible for a CPU coming online or going offline
+	to have this bit set for some time while <tt>cpu_online</tt>
+	returns <tt>false</tt>.
+<li>	For each non-idle CPU that RCU believes is currently online, the grace
+	period invokes <tt>smp_call_function_single()</tt>.
+	If this succeeds, the CPU was fully online.
+	Failure indicates that the CPU is in the process of coming online
+	or going offline, in which case it is necessary to wait for a
+	short time period and try again.
+	The purpose of this wait (or series of waits, as the case may be)
+	is to permit a concurrent CPU-hotplug operation to complete.
+<li>	In the case of RCU-sched, one of the last acts of an outgoing CPU
+	is to invoke <tt>rcu_report_dead()</tt>, which
+	reports a quiescent state for that CPU.
+	However, this is likely paranoia-induced redundancy. <!-- @@@ -->
+</ol>
+
+<table>
+<tr><th>&nbsp;</th></tr>
+<tr><th align="left">Quick Quiz:</th></tr>
+<tr><td>
+	Why all the dancing around with multiple counters and masks
+	tracking CPUs that were once online?
+	Why not just have a single set of masks tracking the currently
+	online CPUs and be done with it?
+</td></tr>
+<tr><th align="left">Answer:</th></tr>
+<tr><td bgcolor="#ffffff"><font color="ffffff">
+	Maintaining single set of masks tracking the online CPUs <i>sounds</i>
+	easier, at least until you try working out all the race conditions
+	between grace-period initialization and CPU-hotplug operations.
+	For example, suppose initialization is progressing down the
+	tree while a CPU-offline operation is progressing up the tree.
+	This situation can result in bits set at the top of the tree
+	that have no counterparts at the bottom of the tree.
+	Those bits will never be cleared, which will result in
+	grace-period hangs.
+	In short, that way lies madness, to say nothing of a great many
+	bugs, hangs, and deadlocks.
+
+	<p><font color="ffffff">
+	In contrast, the current multi-mask multi-counter scheme ensures
+	that grace-period initialization will always see consistent masks
+	up and down the tree, which brings significant simplifications
+	over the single-mask method.
+
+	<p><font color="ffffff">
+	This is an instance of
+	<a href="http://www.cs.columbia.edu/~library/TR-repository/reports/reports-1992/cucs-039-92.ps.gz"><font color="ffffff">
+	deferring work in order to avoid synchronization</a>.
+	Lazily recording CPU-hotplug events at the beginning of the next
+	grace period greatly simplifies maintenance of the CPU-tracking
+	bitmasks in the <tt>rcu_node</tt> tree.
+</font></td></tr>
+<tr><td>&nbsp;</td></tr>
+</table>
+
+<h2><a name="Expedited Grace Period Refinements">
+Expedited Grace Period Refinements</a></h2>
+
+<ol>
+<li>	<a href="#Idle-CPU Checks">Idle-CPU checks</a>.
+<li>	<a href="#Batching via Sequence Counter">
+	Batching via sequence counter</a>.
+<li>	<a href="#Funnel Locking and Wait/Wakeup">
+	Funnel locking and wait/wakeup</a>.
+<li>	<a href="#Use of Workqueues">Use of Workqueues</a>.
+<li>	<a href="#Stall Warnings">Stall warnings</a>.
+<li>	<a href="#Mid-Boot Operation">Mid-boot operation</a>.
+</ol>
+
+<h3><a name="Idle-CPU Checks">Idle-CPU Checks</a></h3>
+
+<p>
+Each expedited grace period checks for idle CPUs when initially forming
+the mask of CPUs to be IPIed and again just before IPIing a CPU
+(both checks are carried out by <tt>sync_rcu_exp_select_cpus()</tt>).
+If the CPU is idle at any time between those two times, the CPU will
+not be IPIed.
+Instead, the task pushing the grace period forward will include the
+idle CPUs in the mask passed to <tt>rcu_report_exp_cpu_mult()</tt>.
+
+<p>
+For RCU-sched, there is an additional check:
+If the IPI has interrupted the idle loop, then
+<tt>rcu_exp_handler()</tt> invokes <tt>rcu_report_exp_rdp()</tt>
+to report the corresponding quiescent state.
+
+<p>
+For RCU-preempt, there is no specific check for idle in the
+IPI handler (<tt>rcu_exp_handler()</tt>), but because
+RCU read-side critical sections are not permitted within the
+idle loop, if <tt>rcu_exp_handler()</tt> sees that the CPU is within
+RCU read-side critical section, the CPU cannot possibly be idle.
+Otherwise, <tt>rcu_exp_handler()</tt> invokes
+<tt>rcu_report_exp_rdp()</tt> to report the corresponding quiescent
+state, regardless of whether or not that quiescent state was due to
+the CPU being idle.
+
+<p>
+In summary, RCU expedited grace periods check for idle when building
+the bitmask of CPUs that must be IPIed, just before sending each IPI,
+and (either explicitly or implicitly) within the IPI handler.
+
+<h3><a name="Batching via Sequence Counter">
+Batching via Sequence Counter</a></h3>
+
+<p>
+If each grace-period request was carried out separately, expedited
+grace periods would have abysmal scalability and
+problematic high-load characteristics.
+Because each grace-period operation can serve an unlimited number of
+updates, it is important to <i>batch</i> requests, so that a single
+expedited grace-period operation will cover all requests in the
+corresponding batch.
+
+<p>
+This batching is controlled by a sequence counter named
+<tt>-&gt;expedited_sequence</tt> in the <tt>rcu_state</tt> structure.
+This counter has an odd value when there is an expedited grace period
+in progress and an even value otherwise, so that dividing the counter
+value by two gives the number of completed grace periods.
+During any given update request, the counter must transition from
+even to odd and then back to even, thus indicating that a grace
+period has elapsed.
+Therefore, if the initial value of the counter is <tt>s</tt>,
+the updater must wait until the counter reaches at least the
+value <tt>(s+3)&amp;~0x1</tt>.
+This counter is managed by the following access functions:
+
+<ol>
+<li>	<tt>rcu_exp_gp_seq_start()</tt>, which marks the start of
+	an expedited grace period.
+<li>	<tt>rcu_exp_gp_seq_end()</tt>, which marks the end of an
+	expedited grace period.
+<li>	<tt>rcu_exp_gp_seq_snap()</tt>, which obtains a snapshot of
+	the counter.
+<li>	<tt>rcu_exp_gp_seq_done()</tt>, which returns <tt>true</tt>
+	if a full expedited grace period has elapsed since the
+	corresponding call to <tt>rcu_exp_gp_seq_snap()</tt>.
+</ol>
+
+<p>
+Again, only one request in a given batch need actually carry out
+a grace-period operation, which means there must be an efficient
+way to identify which of many concurrent reqeusts will initiate
+the grace period, and that there be an efficient way for the
+remaining requests to wait for that grace period to complete.
+However, that is the topic of the next section.
+
+<h3><a name="Funnel Locking and Wait/Wakeup">
+Funnel Locking and Wait/Wakeup</a></h3>
+
+<p>
+The natural way to sort out which of a batch of updaters will initiate
+the expedited grace period is to use the <tt>rcu_node</tt> combining
+tree, as implemented by the <tt>exp_funnel_lock()</tt> function.
+The first updater corresponding to a given grace period arriving
+at a given <tt>rcu_node</tt> structure records its desired grace-period
+sequence number in the <tt>-&gt;exp_seq_rq</tt> field and moves up
+to the next level in the tree.
+Otherwise, if the <tt>-&gt;exp_seq_rq</tt> field already contains
+the sequence number for the desired grace period or some later one,
+the updater blocks on one of four wait queues in the
+<tt>-&gt;exp_wq[]</tt> array, using the second-from-bottom
+and third-from bottom bits as an index.
+An <tt>-&gt;exp_lock</tt> field in the <tt>rcu_node</tt> structure
+synchronizes access to these fields.
+
+<p>
+An empty <tt>rcu_node</tt> tree is shown in the following diagram,
+with the white cells representing the <tt>-&gt;exp_seq_rq</tt> field
+and the red cells representing the elements of the
+<tt>-&gt;exp_wq[]</tt> array.
+
+<p><img src="Funnel0.svg" alt="Funnel0.svg" width="75%">
+
+<p>
+The next diagram shows the situation after the arrival of Task&nbsp;A
+and Task&nbsp;B at the leftmost and rightmost leaf <tt>rcu_node</tt>
+structures, respectively.
+The current value of the <tt>rcu_state</tt> structure's
+<tt>-&gt;expedited_sequence</tt> field is zero, so adding three and
+clearing the bottom bit results in the value two, which both tasks
+record in the <tt>-&gt;exp_seq_rq</tt> field of their respective
+<tt>rcu_node</tt> structures:
+
+<p><img src="Funnel1.svg" alt="Funnel1.svg" width="75%">
+
+<p>
+Each of Tasks&nbsp;A and&nbsp;B will move up to the root
+<tt>rcu_node</tt> structure.
+Suppose that Task&nbsp;A wins, recording its desired grace-period sequence
+number and resulting in the state shown below:
+
+<p><img src="Funnel2.svg" alt="Funnel2.svg" width="75%">
+
+<p>
+Task&nbsp;A now advances to initiate a new grace period, while Task&nbsp;B
+moves up to the root <tt>rcu_node</tt> structure, and, seeing that
+its desired sequence number is already recorded, blocks on
+<tt>-&gt;exp_wq[1]</tt>.
+
+<table>
+<tr><th>&nbsp;</th></tr>
+<tr><th align="left">Quick Quiz:</th></tr>
+<tr><td>
+	Why <tt>-&gt;exp_wq[1]</tt>?
+	Given that the value of these tasks' desired sequence number is
+	two, so shouldn't they instead block on <tt>-&gt;exp_wq[2]</tt>?
+</td></tr>
+<tr><th align="left">Answer:</th></tr>
+<tr><td bgcolor="#ffffff"><font color="ffffff">
+	No.
+
+	<p><font color="ffffff">
+	Recall that the bottom bit of the desired sequence number indicates
+	whether or not a grace period is currently in progress.
+	It is therefore necessary to shift the sequence number right one
+	bit position to obtain the number of the grace period.
+	This results in <tt>-&gt;exp_wq[1]</tt>.
+</font></td></tr>
+<tr><td>&nbsp;</td></tr>
+</table>
+
+<p>
+If Tasks&nbsp;C and&nbsp;D also arrive at this point, they will compute the
+same desired grace-period sequence number, and see that both leaf
+<tt>rcu_node</tt> structures already have that value recorded.
+They will therefore block on their respective <tt>rcu_node</tt>
+structures' <tt>-&gt;exp_wq[1]</tt> fields, as shown below:
+
+<p><img src="Funnel3.svg" alt="Funnel3.svg" width="75%">
+
+<p>
+Task&nbsp;A now acquires the <tt>rcu_state</tt> structure's
+<tt>-&gt;exp_mutex</tt> and initiates the grace period, which
+increments <tt>-&gt;expedited_sequence</tt>.
+Therefore, if Tasks&nbsp;E and&nbsp;F arrive, they will compute
+a desired sequence number of 4 and will record this value as
+shown below:
+
+<p><img src="Funnel4.svg" alt="Funnel4.svg" width="75%">
+
+<p>
+Tasks&nbsp;E and&nbsp;F will propagate up the <tt>rcu_node</tt>
+combining tree, with Task&nbsp;F blocking on the root <tt>rcu_node</tt>
+structure and Task&nbsp;E wait for Task&nbsp;A to finish so that
+it can start the next grace period.
+The resulting state is as shown below:
+
+<p><img src="Funnel5.svg" alt="Funnel5.svg" width="75%">
+
+<p>
+Once the grace period completes, Task&nbsp;A
+starts waking up the tasks waiting for this grace period to complete,
+increments the <tt>-&gt;expedited_sequence</tt>,
+acquires the <tt>-&gt;exp_wake_mutex</tt> and then releases the
+<tt>-&gt;exp_mutex</tt>.
+This results in the following state:
+
+<p><img src="Funnel6.svg" alt="Funnel6.svg" width="75%">
+
+<p>
+Task&nbsp;E can then acquire <tt>-&gt;exp_mutex</tt> and increment
+<tt>-&gt;expedited_sequence</tt> to the value three.
+If new tasks&nbsp;G and&nbsp;H arrive and moves up the combining tree at the
+same time, the state will be as follows:
+
+<p><img src="Funnel7.svg" alt="Funnel7.svg" width="75%">
+
+<p>
+Note that three of the root <tt>rcu_node</tt> structure's
+waitqueues are now occupied.
+However, at some point, Task&nbsp;A will wake up the
+tasks blocked on the <tt>-&gt;exp_wq</tt> waitqueues, resulting
+in the following state:
+
+<p><img src="Funnel8.svg" alt="Funnel8.svg" width="75%">
+
+<p>
+Execution will continue with Tasks&nbsp;E and&nbsp;H completing
+their grace periods and carrying out their wakeups.
+
+<table>
+<tr><th>&nbsp;</th></tr>
+<tr><th align="left">Quick Quiz:</th></tr>
+<tr><td>
+	What happens if Task&nbsp;A takes so long to do its wakeups
+	that Task&nbsp;E's grace period completes?
+</td></tr>
+<tr><th align="left">Answer:</th></tr>
+<tr><td bgcolor="#ffffff"><font color="ffffff">
+	Then Task&nbsp;E will block on the <tt>-&gt;exp_wake_mutex</tt>,
+	which will also prevent it from releasing <tt>-&gt;exp_mutex</tt>,
+	which in turn will prevent the next grace period from starting.
+	This last is important in preventing overflow of the
+	<tt>-&gt;exp_wq[]</tt> array.
+</font></td></tr>
+<tr><td>&nbsp;</td></tr>
+</table>
+
+<h3><a name="Use of Workqueues">Use of Workqueues</a></h3>
+
+<p>
+In earlier implementations, the task requesting the expedited
+grace period also drove it to completion.
+This straightforward approach had the disadvantage of needing to
+account for POSIX signals sent to user tasks,
+so more recent implemementations use the Linux kernel's
+<a href="https://www.kernel.org/doc/Documentation/core-api/workqueue.rst">workqueues</a>.
+
+<p>
+The requesting task still does counter snapshotting and funnel-lock
+processing, but the task reaching the top of the funnel lock
+does a <tt>schedule_work()</tt> (from <tt>_synchronize_rcu_expedited()</tt>
+so that a workqueue kthread does the actual grace-period processing.
+Because workqueue kthreads do not accept POSIX signals, grace-period-wait
+processing need not allow for POSIX signals.
+
+In addition, this approach allows wakeups for the previous expedited
+grace period to be overlapped with processing for the next expedited
+grace period.
+Because there are only four sets of waitqueues, it is necessary to
+ensure that the previous grace period's wakeups complete before the
+next grace period's wakeups start.
+This is handled by having the <tt>-&gt;exp_mutex</tt>
+guard expedited grace-period processing and the
+<tt>-&gt;exp_wake_mutex</tt> guard wakeups.
+The key point is that the <tt>-&gt;exp_mutex</tt> is not released
+until the first wakeup is complete, which means that the
+<tt>-&gt;exp_wake_mutex</tt> has already been acquired at that point.
+This approach ensures that the previous grace period's wakeups can
+be carried out while the current grace period is in process, but
+that these wakeups will complete before the next grace period starts.
+This means that only three waitqueues are required, guaranteeing that
+the four that are provided are sufficient.
+
+<h3><a name="Stall Warnings">Stall Warnings</a></h3>
+
+<p>
+Expediting grace periods does nothing to speed things up when RCU
+readers take too long, and therefore expedited grace periods check
+for stalls just as normal grace periods do.
+
+<table>
+<tr><th>&nbsp;</th></tr>
+<tr><th align="left">Quick Quiz:</th></tr>
+<tr><td>
+	But why not just let the normal grace-period machinery
+	detect the stalls, given that a given reader must block
+	both normal and expedited grace periods?
+</td></tr>
+<tr><th align="left">Answer:</th></tr>
+<tr><td bgcolor="#ffffff"><font color="ffffff">
+	Because it is quite possible that at a given time there
+	is no normal grace period in progress, in which case the
+	normal grace period cannot emit a stall warning.
+</font></td></tr>
+<tr><td>&nbsp;</td></tr>
+</table>
+
+The <tt>synchronize_sched_expedited_wait()</tt> function loops waiting
+for the expedited grace period to end, but with a timeout set to the
+current RCU CPU stall-warning time.
+If this time is exceeded, any CPUs or <tt>rcu_node</tt> structures
+blocking the current grace period are printed.
+Each stall warning results in another pass through the loop, but the
+second and subsequent passes use longer stall times.
+
+<h3><a name="Mid-Boot Operation">Mid-boot operation</a></h3>
+
+<p>
+The use of workqueues has the advantage that the expedited
+grace-period code need not worry about POSIX signals.
+Unfortunately, it has the
+corresponding disadvantage that workqueues cannot be used until
+they are initialized, which does not happen until some time after
+the scheduler spawns the first task.
+Given that there are parts of the kernel that really do want to
+execute grace periods during this mid-boot &ldquo;dead zone&rdquo;,
+expedited grace periods must do something else during thie time.
+
+<p>
+What they do is to fall back to the old practice of requiring that the
+requesting task drive the expedited grace period, as was the case
+before the use of workqueues.
+However, the requesting task is only required to drive the grace period
+during the mid-boot dead zone.
+Before mid-boot, a synchronous grace period is a no-op.
+Some time after mid-boot, workqueues are used.
+
+<p>
+Non-expedited non-SRCU synchronous grace periods must also operate
+normally during mid-boot.
+This is handled by causing non-expedited grace periods to take the
+expedited code path during mid-boot.
+
+<p>
+The current code assumes that there are no POSIX signals during
+the mid-boot dead zone.
+However, if an overwhelming need for POSIX signals somehow arises,
+appropriate adjustments can be made to the expedited stall-warning code.
+One such adjustment would reinstate the pre-workqueue stall-warning
+checks, but only during the mid-boot dead zone.
+
+<p>
+With this refinement, synchronous grace periods can now be used from
+task context pretty much any time during the life of the kernel.
+That is, aside from some points in the suspend, hibernate, or shutdown
+code path.
+
+<h3><a name="Summary">
+Summary</a></h3>
+
+<p>
+Expedited grace periods use a sequence-number approach to promote
+batching, so that a single grace-period operation can serve numerous
+requests.
+A funnel lock is used to efficiently identify the one task out of
+a concurrent group that will request the grace period.
+All members of the group will block on waitqueues provided in
+the <tt>rcu_node</tt> structure.
+The actual grace-period processing is carried out by a workqueue.
+
+<p>
+CPU-hotplug operations are noted lazily in order to prevent the need
+for tight synchronization between expedited grace periods and
+CPU-hotplug operations.
+The dyntick-idle counters are used to avoid sending IPIs to idle CPUs,
+at least in the common case.
+RCU-preempt and RCU-sched use different IPI handlers and different
+code to respond to the state changes carried out by those handlers,
+but otherwise use common code.
+
+<p>
+Quiescent states are tracked using the <tt>rcu_node</tt> tree,
+and once all necessary quiescent states have been reported,
+all tasks waiting on this expedited grace period are awakened.
+A pair of mutexes are used to allow one grace period's wakeups
+to proceed concurrently with the next grace period's processing.
+
+<p>
+This combination of mechanisms allows expedited grace periods to
+run reasonably efficiently.
+However, for non-time-critical tasks, normal grace periods should be
+used instead because their longer duration permits much higher
+degrees of batching, and thus much lower per-request overheads.
+
+</body></html>

Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst

@@ -1,521 +0,0 @@
-=================================================
-A Tour Through TREE_RCU's Expedited Grace Periods
-=================================================
-
-Introduction
-============
-
-This document describes RCU's expedited grace periods.
-Unlike RCU's normal grace periods, which accept long latencies to attain
-high efficiency and minimal disturbance, expedited grace periods accept
-lower efficiency and significant disturbance to attain shorter latencies.
-
-There are two flavors of RCU (RCU-preempt and RCU-sched), with an earlier
-third RCU-bh flavor having been implemented in terms of the other two.
-Each of the two implementations is covered in its own section.
-
-Expedited Grace Period Design
-=============================
-
-The expedited RCU grace periods cannot be accused of being subtle,
-given that they for all intents and purposes hammer every CPU that
-has not yet provided a quiescent state for the current expedited
-grace period.
-The one saving grace is that the hammer has grown a bit smaller
-over time:  The old call to ``try_stop_cpus()`` has been
-replaced with a set of calls to ``smp_call_function_single()``,
-each of which results in an IPI to the target CPU.
-The corresponding handler function checks the CPU's state, motivating
-a faster quiescent state where possible, and triggering a report
-of that quiescent state.
-As always for RCU, once everything has spent some time in a quiescent
-state, the expedited grace period has completed.
-
-The details of the ``smp_call_function_single()`` handler's
-operation depend on the RCU flavor, as described in the following
-sections.
-
-RCU-preempt Expedited Grace Periods
-===================================
-
-``CONFIG_PREEMPT=y`` kernels implement RCU-preempt.
-The overall flow of the handling of a given CPU by an RCU-preempt
-expedited grace period is shown in the following diagram:
-
-.. kernel-figure:: ExpRCUFlow.svg
-
-The solid arrows denote direct action, for example, a function call.
-The dotted arrows denote indirect action, for example, an IPI
-or a state that is reached after some time.
-
-If a given CPU is offline or idle, ``synchronize_rcu_expedited()``
-will ignore it because idle and offline CPUs are already residing
-in quiescent states.
-Otherwise, the expedited grace period will use
-``smp_call_function_single()`` to send the CPU an IPI, which
-is handled by ``rcu_exp_handler()``.
-
-However, because this is preemptible RCU, ``rcu_exp_handler()``
-can check to see if the CPU is currently running in an RCU read-side
-critical section.
-If not, the handler can immediately report a quiescent state.
-Otherwise, it sets flags so that the outermost ``rcu_read_unlock()``
-invocation will provide the needed quiescent-state report.
-This flag-setting avoids the previous forced preemption of all
-CPUs that might have RCU read-side critical sections.
-In addition, this flag-setting is done so as to avoid increasing
-the overhead of the common-case fastpath through the scheduler.
-
-Again because this is preemptible RCU, an RCU read-side critical section
-can be preempted.
-When that happens, RCU will enqueue the task, which will the continue to
-block the current expedited grace period until it resumes and finds its
-outermost ``rcu_read_unlock()``.
-The CPU will report a quiescent state just after enqueuing the task because
-the CPU is no longer blocking the grace period.
-It is instead the preempted task doing the blocking.
-The list of blocked tasks is managed by ``rcu_preempt_ctxt_queue()``,
-which is called from ``rcu_preempt_note_context_switch()``, which
-in turn is called from ``rcu_note_context_switch()``, which in
-turn is called from the scheduler.
-
-
-+-----------------------------------------------------------------------+
-| **Quick Quiz**:                                                       |
-+-----------------------------------------------------------------------+
-| Why not just have the expedited grace period check the state of all   |
-| the CPUs? After all, that would avoid all those real-time-unfriendly  |
-| IPIs.                                                                 |
-+-----------------------------------------------------------------------+
-| **Answer**:                                                           |
-+-----------------------------------------------------------------------+
-| Because we want the RCU read-side critical sections to run fast,      |
-| which means no memory barriers. Therefore, it is not possible to      |
-| safely check the state from some other CPU. And even if it was        |
-| possible to safely check the state, it would still be necessary to    |
-| IPI the CPU to safely interact with the upcoming                      |
-| ``rcu_read_unlock()`` invocation, which means that the remote state   |
-| testing would not help the worst-case latency that real-time          |
-| applications care about.                                              |
-|                                                                       |
-| One way to prevent your real-time application from getting hit with   |
-| these IPIs is to build your kernel with ``CONFIG_NO_HZ_FULL=y``. RCU  |
-| would then perceive the CPU running your application as being idle,   |
-| and it would be able to safely detect that state without needing to   |
-| IPI the CPU.                                                          |
-+-----------------------------------------------------------------------+
-
-Please note that this is just the overall flow: Additional complications
-can arise due to races with CPUs going idle or offline, among other
-things.
-
-RCU-sched Expedited Grace Periods
----------------------------------
-
-``CONFIG_PREEMPT=n`` kernels implement RCU-sched. The overall flow of
-the handling of a given CPU by an RCU-sched expedited grace period is
-shown in the following diagram:
-
-.. kernel-figure:: ExpSchedFlow.svg
-
-As with RCU-preempt, RCU-sched's ``synchronize_rcu_expedited()`` ignores
-offline and idle CPUs, again because they are in remotely detectable
-quiescent states. However, because the ``rcu_read_lock_sched()`` and
-``rcu_read_unlock_sched()`` leave no trace of their invocation, in
-general it is not possible to tell whether or not the current CPU is in
-an RCU read-side critical section. The best that RCU-sched's
-``rcu_exp_handler()`` can do is to check for idle, on the off-chance
-that the CPU went idle while the IPI was in flight. If the CPU is idle,
-then ``rcu_exp_handler()`` reports the quiescent state.
-
-Otherwise, the handler forces a future context switch by setting the
-NEED_RESCHED flag of the current task's thread flag and the CPU preempt
-counter. At the time of the context switch, the CPU reports the
-quiescent state. Should the CPU go offline first, it will report the
-quiescent state at that time.
-
-Expedited Grace Period and CPU Hotplug
---------------------------------------
-
-The expedited nature of expedited grace periods require a much tighter
-interaction with CPU hotplug operations than is required for normal
-grace periods. In addition, attempting to IPI offline CPUs will result
-in splats, but failing to IPI online CPUs can result in too-short grace
-periods. Neither option is acceptable in production kernels.
-
-The interaction between expedited grace periods and CPU hotplug
-operations is carried out at several levels:
-
-#. The number of CPUs that have ever been online is tracked by the
-   ``rcu_state`` structure's ``->ncpus`` field. The ``rcu_state``
-   structure's ``->ncpus_snap`` field tracks the number of CPUs that
-   have ever been online at the beginning of an RCU expedited grace
-   period. Note that this number never decreases, at least in the
-   absence of a time machine.
-#. The identities of the CPUs that have ever been online is tracked by
-   the ``rcu_node`` structure's ``->expmaskinitnext`` field. The
-   ``rcu_node`` structure's ``->expmaskinit`` field tracks the
-   identities of the CPUs that were online at least once at the
-   beginning of the most recent RCU expedited grace period. The
-   ``rcu_state`` structure's ``->ncpus`` and ``->ncpus_snap`` fields are
-   used to detect when new CPUs have come online for the first time,
-   that is, when the ``rcu_node`` structure's ``->expmaskinitnext``
-   field has changed since the beginning of the last RCU expedited grace
-   period, which triggers an update of each ``rcu_node`` structure's
-   ``->expmaskinit`` field from its ``->expmaskinitnext`` field.
-#. Each ``rcu_node`` structure's ``->expmaskinit`` field is used to
-   initialize that structure's ``->expmask`` at the beginning of each
-   RCU expedited grace period. This means that only those CPUs that have
-   been online at least once will be considered for a given grace
-   period.
-#. Any CPU that goes offline will clear its bit in its leaf ``rcu_node``
-   structure's ``->qsmaskinitnext`` field, so any CPU with that bit
-   clear can safely be ignored. However, it is possible for a CPU coming
-   online or going offline to have this bit set for some time while
-   ``cpu_online`` returns ``false``.
-#. For each non-idle CPU that RCU believes is currently online, the
-   grace period invokes ``smp_call_function_single()``. If this
-   succeeds, the CPU was fully online. Failure indicates that the CPU is
-   in the process of coming online or going offline, in which case it is
-   necessary to wait for a short time period and try again. The purpose
-   of this wait (or series of waits, as the case may be) is to permit a
-   concurrent CPU-hotplug operation to complete.
-#. In the case of RCU-sched, one of the last acts of an outgoing CPU is
-   to invoke ``rcu_report_dead()``, which reports a quiescent state for
-   that CPU. However, this is likely paranoia-induced redundancy.
-
-+-----------------------------------------------------------------------+
-| **Quick Quiz**:                                                       |
-+-----------------------------------------------------------------------+
-| Why all the dancing around with multiple counters and masks tracking  |
-| CPUs that were once online? Why not just have a single set of masks   |
-| tracking the currently online CPUs and be done with it?               |
-+-----------------------------------------------------------------------+
-| **Answer**:                                                           |
-+-----------------------------------------------------------------------+
-| Maintaining single set of masks tracking the online CPUs *sounds*     |
-| easier, at least until you try working out all the race conditions    |
-| between grace-period initialization and CPU-hotplug operations. For   |
-| example, suppose initialization is progressing down the tree while a  |
-| CPU-offline operation is progressing up the tree. This situation can  |
-| result in bits set at the top of the tree that have no counterparts   |
-| at the bottom of the tree. Those bits will never be cleared, which    |
-| will result in grace-period hangs. In short, that way lies madness,   |
-| to say nothing of a great many bugs, hangs, and deadlocks.            |
-| In contrast, the current multi-mask multi-counter scheme ensures that |
-| grace-period initialization will always see consistent masks up and   |
-| down the tree, which brings significant simplifications over the      |
-| single-mask method.                                                   |
-|                                                                       |
-| This is an instance of `deferring work in order to avoid              |
-| synchronization <http://www.cs.columbia.edu/~library/TR-repository/re |
-| ports/reports-1992/cucs-039-92.ps.gz>`__.                             |
-| Lazily recording CPU-hotplug events at the beginning of the next      |
-| grace period greatly simplifies maintenance of the CPU-tracking       |
-| bitmasks in the ``rcu_node`` tree.                                    |
-+-----------------------------------------------------------------------+
-
-Expedited Grace Period Refinements
-----------------------------------
-
-Idle-CPU Checks
-~~~~~~~~~~~~~~~
-
-Each expedited grace period checks for idle CPUs when initially forming
-the mask of CPUs to be IPIed and again just before IPIing a CPU (both
-checks are carried out by ``sync_rcu_exp_select_cpus()``). If the CPU is
-idle at any time between those two times, the CPU will not be IPIed.
-Instead, the task pushing the grace period forward will include the idle
-CPUs in the mask passed to ``rcu_report_exp_cpu_mult()``.
-
-For RCU-sched, there is an additional check: If the IPI has interrupted
-the idle loop, then ``rcu_exp_handler()`` invokes
-``rcu_report_exp_rdp()`` to report the corresponding quiescent state.
-
-For RCU-preempt, there is no specific check for idle in the IPI handler
-(``rcu_exp_handler()``), but because RCU read-side critical sections are
-not permitted within the idle loop, if ``rcu_exp_handler()`` sees that
-the CPU is within RCU read-side critical section, the CPU cannot
-possibly be idle. Otherwise, ``rcu_exp_handler()`` invokes
-``rcu_report_exp_rdp()`` to report the corresponding quiescent state,
-regardless of whether or not that quiescent state was due to the CPU
-being idle.
-
-In summary, RCU expedited grace periods check for idle when building the
-bitmask of CPUs that must be IPIed, just before sending each IPI, and
-(either explicitly or implicitly) within the IPI handler.
-
-Batching via Sequence Counter
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If each grace-period request was carried out separately, expedited grace
-periods would have abysmal scalability and problematic high-load
-characteristics. Because each grace-period operation can serve an
-unlimited number of updates, it is important to *batch* requests, so
-that a single expedited grace-period operation will cover all requests
-in the corresponding batch.
-
-This batching is controlled by a sequence counter named
-``->expedited_sequence`` in the ``rcu_state`` structure. This counter
-has an odd value when there is an expedited grace period in progress and
-an even value otherwise, so that dividing the counter value by two gives
-the number of completed grace periods. During any given update request,
-the counter must transition from even to odd and then back to even, thus
-indicating that a grace period has elapsed. Therefore, if the initial
-value of the counter is ``s``, the updater must wait until the counter
-reaches at least the value ``(s+3)&~0x1``. This counter is managed by
-the following access functions:
-
-#. ``rcu_exp_gp_seq_start()``, which marks the start of an expedited
-   grace period.
-#. ``rcu_exp_gp_seq_end()``, which marks the end of an expedited grace
-   period.
-#. ``rcu_exp_gp_seq_snap()``, which obtains a snapshot of the counter.
-#. ``rcu_exp_gp_seq_done()``, which returns ``true`` if a full expedited
-   grace period has elapsed since the corresponding call to
-   ``rcu_exp_gp_seq_snap()``.
-
-Again, only one request in a given batch need actually carry out a
-grace-period operation, which means there must be an efficient way to
-identify which of many concurrent reqeusts will initiate the grace
-period, and that there be an efficient way for the remaining requests to
-wait for that grace period to complete. However, that is the topic of
-the next section.
-
-Funnel Locking and Wait/Wakeup
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The natural way to sort out which of a batch of updaters will initiate
-the expedited grace period is to use the ``rcu_node`` combining tree, as
-implemented by the ``exp_funnel_lock()`` function. The first updater
-corresponding to a given grace period arriving at a given ``rcu_node``
-structure records its desired grace-period sequence number in the
-``->exp_seq_rq`` field and moves up to the next level in the tree.
-Otherwise, if the ``->exp_seq_rq`` field already contains the sequence
-number for the desired grace period or some later one, the updater
-blocks on one of four wait queues in the ``->exp_wq[]`` array, using the
-second-from-bottom and third-from bottom bits as an index. An
-``->exp_lock`` field in the ``rcu_node`` structure synchronizes access
-to these fields.
-
-An empty ``rcu_node`` tree is shown in the following diagram, with the
-white cells representing the ``->exp_seq_rq`` field and the red cells
-representing the elements of the ``->exp_wq[]`` array.
-
-.. kernel-figure:: Funnel0.svg
-
-The next diagram shows the situation after the arrival of Task A and
-Task B at the leftmost and rightmost leaf ``rcu_node`` structures,
-respectively. The current value of the ``rcu_state`` structure's
-``->expedited_sequence`` field is zero, so adding three and clearing the
-bottom bit results in the value two, which both tasks record in the
-``->exp_seq_rq`` field of their respective ``rcu_node`` structures:
-
-.. kernel-figure:: Funnel1.svg
-
-Each of Tasks A and B will move up to the root ``rcu_node`` structure.
-Suppose that Task A wins, recording its desired grace-period sequence
-number and resulting in the state shown below:
-
-.. kernel-figure:: Funnel2.svg
-
-Task A now advances to initiate a new grace period, while Task B moves
-up to the root ``rcu_node`` structure, and, seeing that its desired
-sequence number is already recorded, blocks on ``->exp_wq[1]``.
-
-+-----------------------------------------------------------------------+
-| **Quick Quiz**:                                                       |
-+-----------------------------------------------------------------------+
-| Why ``->exp_wq[1]``? Given that the value of these tasks' desired     |
-| sequence number is two, so shouldn't they instead block on            |
-| ``->exp_wq[2]``?                                                      |
-+-----------------------------------------------------------------------+
-| **Answer**:                                                           |
-+-----------------------------------------------------------------------+
-| No.                                                                   |
-| Recall that the bottom bit of the desired sequence number indicates   |
-| whether or not a grace period is currently in progress. It is         |
-| therefore necessary to shift the sequence number right one bit        |
-| position to obtain the number of the grace period. This results in    |
-| ``->exp_wq[1]``.                                                      |
-+-----------------------------------------------------------------------+
-
-If Tasks C and D also arrive at this point, they will compute the same
-desired grace-period sequence number, and see that both leaf
-``rcu_node`` structures already have that value recorded. They will
-therefore block on their respective ``rcu_node`` structures'
-``->exp_wq[1]`` fields, as shown below:
-
-.. kernel-figure:: Funnel3.svg
-
-Task A now acquires the ``rcu_state`` structure's ``->exp_mutex`` and
-initiates the grace period, which increments ``->expedited_sequence``.
-Therefore, if Tasks E and F arrive, they will compute a desired sequence
-number of 4 and will record this value as shown below:
-
-.. kernel-figure:: Funnel4.svg
-
-Tasks E and F will propagate up the ``rcu_node`` combining tree, with
-Task F blocking on the root ``rcu_node`` structure and Task E wait for
-Task A to finish so that it can start the next grace period. The
-resulting state is as shown below:
-
-.. kernel-figure:: Funnel5.svg
-
-Once the grace period completes, Task A starts waking up the tasks
-waiting for this grace period to complete, increments the
-``->expedited_sequence``, acquires the ``->exp_wake_mutex`` and then
-releases the ``->exp_mutex``. This results in the following state:
-
-.. kernel-figure:: Funnel6.svg
-
-Task E can then acquire ``->exp_mutex`` and increment
-``->expedited_sequence`` to the value three. If new tasks G and H arrive
-and moves up the combining tree at the same time, the state will be as
-follows:
-
-.. kernel-figure:: Funnel7.svg
-
-Note that three of the root ``rcu_node`` structure's waitqueues are now
-occupied. However, at some point, Task A will wake up the tasks blocked
-on the ``->exp_wq`` waitqueues, resulting in the following state:
-
-.. kernel-figure:: Funnel8.svg
-
-Execution will continue with Tasks E and H completing their grace
-periods and carrying out their wakeups.
-
-+-----------------------------------------------------------------------+
-| **Quick Quiz**:                                                       |
-+-----------------------------------------------------------------------+
-| What happens if Task A takes so long to do its wakeups that Task E's  |
-| grace period completes?                                               |
-+-----------------------------------------------------------------------+
-| **Answer**:                                                           |
-+-----------------------------------------------------------------------+
-| Then Task E will block on the ``->exp_wake_mutex``, which will also   |
-| prevent it from releasing ``->exp_mutex``, which in turn will prevent |
-| the next grace period from starting. This last is important in        |
-| preventing overflow of the ``->exp_wq[]`` array.                      |
-+-----------------------------------------------------------------------+
-
-Use of Workqueues
-~~~~~~~~~~~~~~~~~
-
-In earlier implementations, the task requesting the expedited grace
-period also drove it to completion. This straightforward approach had
-the disadvantage of needing to account for POSIX signals sent to user
-tasks, so more recent implemementations use the Linux kernel's
-`workqueues <https://www.kernel.org/doc/Documentation/core-api/workqueue.rst>`__.
-
-The requesting task still does counter snapshotting and funnel-lock
-processing, but the task reaching the top of the funnel lock does a
-``schedule_work()`` (from ``_synchronize_rcu_expedited()`` so that a
-workqueue kthread does the actual grace-period processing. Because
-workqueue kthreads do not accept POSIX signals, grace-period-wait
-processing need not allow for POSIX signals. In addition, this approach
-allows wakeups for the previous expedited grace period to be overlapped
-with processing for the next expedited grace period. Because there are
-only four sets of waitqueues, it is necessary to ensure that the
-previous grace period's wakeups complete before the next grace period's
-wakeups start. This is handled by having the ``->exp_mutex`` guard
-expedited grace-period processing and the ``->exp_wake_mutex`` guard
-wakeups. The key point is that the ``->exp_mutex`` is not released until
-the first wakeup is complete, which means that the ``->exp_wake_mutex``
-has already been acquired at that point. This approach ensures that the
-previous grace period's wakeups can be carried out while the current
-grace period is in process, but that these wakeups will complete before
-the next grace period starts. This means that only three waitqueues are
-required, guaranteeing that the four that are provided are sufficient.
-
-Stall Warnings
-~~~~~~~~~~~~~~
-
-Expediting grace periods does nothing to speed things up when RCU
-readers take too long, and therefore expedited grace periods check for
-stalls just as normal grace periods do.
-
-+-----------------------------------------------------------------------+
-| **Quick Quiz**:                                                       |
-+-----------------------------------------------------------------------+
-| But why not just let the normal grace-period machinery detect the     |
-| stalls, given that a given reader must block both normal and          |
-| expedited grace periods?                                              |
-+-----------------------------------------------------------------------+
-| **Answer**:                                                           |
-+-----------------------------------------------------------------------+
-| Because it is quite possible that at a given time there is no normal  |
-| grace period in progress, in which case the normal grace period       |
-| cannot emit a stall warning.                                          |
-+-----------------------------------------------------------------------+
-
-The ``synchronize_sched_expedited_wait()`` function loops waiting for
-the expedited grace period to end, but with a timeout set to the current
-RCU CPU stall-warning time. If this time is exceeded, any CPUs or
-``rcu_node`` structures blocking the current grace period are printed.
-Each stall warning results in another pass through the loop, but the
-second and subsequent passes use longer stall times.
-
-Mid-boot operation
-~~~~~~~~~~~~~~~~~~
-
-The use of workqueues has the advantage that the expedited grace-period
-code need not worry about POSIX signals. Unfortunately, it has the
-corresponding disadvantage that workqueues cannot be used until they are
-initialized, which does not happen until some time after the scheduler
-spawns the first task. Given that there are parts of the kernel that
-really do want to execute grace periods during this mid-boot “dead
-zone”, expedited grace periods must do something else during thie time.
-
-What they do is to fall back to the old practice of requiring that the
-requesting task drive the expedited grace period, as was the case before
-the use of workqueues. However, the requesting task is only required to
-drive the grace period during the mid-boot dead zone. Before mid-boot, a
-synchronous grace period is a no-op. Some time after mid-boot,
-workqueues are used.
-
-Non-expedited non-SRCU synchronous grace periods must also operate
-normally during mid-boot. This is handled by causing non-expedited grace
-periods to take the expedited code path during mid-boot.
-
-The current code assumes that there are no POSIX signals during the
-mid-boot dead zone. However, if an overwhelming need for POSIX signals
-somehow arises, appropriate adjustments can be made to the expedited
-stall-warning code. One such adjustment would reinstate the
-pre-workqueue stall-warning checks, but only during the mid-boot dead
-zone.
-
-With this refinement, synchronous grace periods can now be used from
-task context pretty much any time during the life of the kernel. That
-is, aside from some points in the suspend, hibernate, or shutdown code
-path.
-
-Summary
-~~~~~~~
-
-Expedited grace periods use a sequence-number approach to promote
-batching, so that a single grace-period operation can serve numerous
-requests. A funnel lock is used to efficiently identify the one task out
-of a concurrent group that will request the grace period. All members of
-the group will block on waitqueues provided in the ``rcu_node``
-structure. The actual grace-period processing is carried out by a
-workqueue.
-
-CPU-hotplug operations are noted lazily in order to prevent the need for
-tight synchronization between expedited grace periods and CPU-hotplug
-operations. The dyntick-idle counters are used to avoid sending IPIs to
-idle CPUs, at least in the common case. RCU-preempt and RCU-sched use
-different IPI handlers and different code to respond to the state
-changes carried out by those handlers, but otherwise use common code.
-
-Quiescent states are tracked using the ``rcu_node`` tree, and once all
-necessary quiescent states have been reported, all tasks waiting on this
-expedited grace period are awakened. A pair of mutexes are used to allow
-one grace period's wakeups to proceed concurrently with the next grace
-period's processing.
-
-This combination of mechanisms allows expedited grace periods to run
-reasonably efficiently. However, for non-time-critical tasks, normal
-grace periods should be used instead because their longer duration
-permits much higher degrees of batching, and thus much lower per-request
-overheads.

Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Diagram.html

@@ -0,0 +1,9 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+        "http://www.w3.org/TR/html4/loose.dtd">
+        <html>
+        <head><title>A Diagram of TREE_RCU's Grace-Period Memory Ordering</title>
+        <meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
+
+<p><img src="TreeRCU-gp.svg" alt="TreeRCU-gp.svg">
+
+</body></html>

Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.html

@@ -0,0 +1,704 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+        "http://www.w3.org/TR/html4/loose.dtd">
+        <html>
+        <head><title>A Tour Through TREE_RCU's Grace-Period Memory Ordering</title>
+        <meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
+
+           <p>August 8, 2017</p>
+           <p>This article was contributed by Paul E.&nbsp;McKenney</p>
+
+<h3>Introduction</h3>
+
+<p>This document gives a rough visual overview of how Tree RCU's
+grace-period memory ordering guarantee is provided.
+
+<ol>
+<li>	<a href="#What Is Tree RCU's Grace Period Memory Ordering Guarantee?">
+	What Is Tree RCU's Grace Period Memory Ordering Guarantee?</a>
+<li>	<a href="#Tree RCU Grace Period Memory Ordering Building Blocks">
+	Tree RCU Grace Period Memory Ordering Building Blocks</a>
+<li>	<a href="#Tree RCU Grace Period Memory Ordering Components">
+	Tree RCU Grace Period Memory Ordering Components</a>
+<li>	<a href="#Putting It All Together">Putting It All Together</a>
+</ol>
+
+<h3><a name="What Is Tree RCU's Grace Period Memory Ordering Guarantee?">
+What Is Tree RCU's Grace Period Memory Ordering Guarantee?</a></h3>
+
+<p>RCU grace periods provide extremely strong memory-ordering guarantees
+for non-idle non-offline code.
+Any code that happens after the end of a given RCU grace period is guaranteed
+to see the effects of all accesses prior to the beginning of that grace
+period that are within RCU read-side critical sections.
+Similarly, any code that happens before the beginning of a given RCU grace
+period is guaranteed to see the effects of all accesses following the end
+of that grace period that are within RCU read-side critical sections.
+
+<p>Note well that RCU-sched read-side critical sections include any region
+of code for which preemption is disabled.
+Given that each individual machine instruction can be thought of as
+an extremely small region of preemption-disabled code, one can think of
+<tt>synchronize_rcu()</tt> as <tt>smp_mb()</tt> on steroids.
+
+<p>RCU updaters use this guarantee by splitting their updates into
+two phases, one of which is executed before the grace period and
+the other of which is executed after the grace period.
+In the most common use case, phase one removes an element from
+a linked RCU-protected data structure, and phase two frees that element.
+For this to work, any readers that have witnessed state prior to the
+phase-one update (in the common case, removal) must not witness state
+following the phase-two update (in the common case, freeing).
+
+<p>The RCU implementation provides this guarantee using a network
+of lock-based critical sections, memory barriers, and per-CPU
+processing, as is described in the following sections.
+
+<h3><a name="Tree RCU Grace Period Memory Ordering Building Blocks">
+Tree RCU Grace Period Memory Ordering Building Blocks</a></h3>
+
+<p>The workhorse for RCU's grace-period memory ordering is the
+critical section for the <tt>rcu_node</tt> structure's
+<tt>-&gt;lock</tt>.
+These critical sections use helper functions for lock acquisition, including
+<tt>raw_spin_lock_rcu_node()</tt>,
+<tt>raw_spin_lock_irq_rcu_node()</tt>, and
+<tt>raw_spin_lock_irqsave_rcu_node()</tt>.
+Their lock-release counterparts are
+<tt>raw_spin_unlock_rcu_node()</tt>,
+<tt>raw_spin_unlock_irq_rcu_node()</tt>, and
+<tt>raw_spin_unlock_irqrestore_rcu_node()</tt>,
+respectively.
+For completeness, a
+<tt>raw_spin_trylock_rcu_node()</tt>
+is also provided.
+The key point is that the lock-acquisition functions, including
+<tt>raw_spin_trylock_rcu_node()</tt>, all invoke
+<tt>smp_mb__after_unlock_lock()</tt> immediately after successful
+acquisition of the lock.
+
+<p>Therefore, for any given <tt>rcu_node</tt> structure, any access
+happening before one of the above lock-release functions will be seen
+by all CPUs as happening before any access happening after a later
+one of the above lock-acquisition functions.
+Furthermore, any access happening before one of the
+above lock-release function on any given CPU will be seen by all
+CPUs as happening before any access happening after a later one
+of the above lock-acquisition functions executing on that same CPU,
+even if the lock-release and lock-acquisition functions are operating
+on different <tt>rcu_node</tt> structures.
+Tree RCU uses these two ordering guarantees to form an ordering
+network among all CPUs that were in any way involved in the grace
+period, including any CPUs that came online or went offline during
+the grace period in question.
+
+<p>The following litmus test exhibits the ordering effects of these
+lock-acquisition and lock-release functions:
+
+<pre>
+ 1 int x, y, z;
+ 2
+ 3 void task0(void)
+ 4 {
+ 5   raw_spin_lock_rcu_node(rnp);
+ 6   WRITE_ONCE(x, 1);
+ 7   r1 = READ_ONCE(y);
+ 8   raw_spin_unlock_rcu_node(rnp);
+ 9 }
+10
+11 void task1(void)
+12 {
+13   raw_spin_lock_rcu_node(rnp);
+14   WRITE_ONCE(y, 1);
+15   r2 = READ_ONCE(z);
+16   raw_spin_unlock_rcu_node(rnp);
+17 }
+18
+19 void task2(void)
+20 {
+21   WRITE_ONCE(z, 1);
+22   smp_mb();
+23   r3 = READ_ONCE(x);
+24 }
+25
+26 WARN_ON(r1 == 0 &amp;&amp; r2 == 0 &amp;&amp; r3 == 0);
+</pre>
+
+<p>The <tt>WARN_ON()</tt> is evaluated at &ldquo;the end of time&rdquo;,
+after all changes have propagated throughout the system.
+Without the <tt>smp_mb__after_unlock_lock()</tt> provided by the
+acquisition functions, this <tt>WARN_ON()</tt> could trigger, for example
+on PowerPC.
+The <tt>smp_mb__after_unlock_lock()</tt> invocations prevent this
+<tt>WARN_ON()</tt> from triggering.
+
+<p>This approach must be extended to include idle CPUs, which need
+RCU's grace-period memory ordering guarantee to extend to any
+RCU read-side critical sections preceding and following the current
+idle sojourn.
+This case is handled by calls to the strongly ordered
+<tt>atomic_add_return()</tt> read-modify-write atomic operation that
+is invoked within <tt>rcu_dynticks_eqs_enter()</tt> at idle-entry
+time and within <tt>rcu_dynticks_eqs_exit()</tt> at idle-exit time.
+The grace-period kthread invokes <tt>rcu_dynticks_snap()</tt> and
+<tt>rcu_dynticks_in_eqs_since()</tt> (both of which invoke
+an <tt>atomic_add_return()</tt> of zero) to detect idle CPUs.
+
+<table>
+<tr><th>&nbsp;</th></tr>
+<tr><th align="left">Quick Quiz:</th></tr>
+<tr><td>
+	But what about CPUs that remain offline for the entire
+	grace period?
+</td></tr>
+<tr><th align="left">Answer:</th></tr>
+<tr><td bgcolor="#ffffff"><font color="ffffff">
+	Such CPUs will be offline at the beginning of the grace period,
+	so the grace period won't expect quiescent states from them.
+	Races between grace-period start and CPU-hotplug operations
+	are mediated by the CPU's leaf <tt>rcu_node</tt> structure's
+	<tt>-&gt;lock</tt> as described above.
+</font></td></tr>
+<tr><td>&nbsp;</td></tr>
+</table>
+
+<p>The approach must be extended to handle one final case, that
+of waking a task blocked in <tt>synchronize_rcu()</tt>.
+This task might be affinitied to a CPU that is not yet aware that
+the grace period has ended, and thus might not yet be subject to
+the grace period's memory ordering.
+Therefore, there is an <tt>smp_mb()</tt> after the return from
+<tt>wait_for_completion()</tt> in the <tt>synchronize_rcu()</tt>
+code path.
+
+<table>
+<tr><th>&nbsp;</th></tr>
+<tr><th align="left">Quick Quiz:</th></tr>
+<tr><td>
+	What?  Where???
+	I don't see any <tt>smp_mb()</tt> after the return from
+	<tt>wait_for_completion()</tt>!!!
+</td></tr>
+<tr><th align="left">Answer:</th></tr>
+<tr><td bgcolor="#ffffff"><font color="ffffff">
+	That would be because I spotted the need for that
+	<tt>smp_mb()</tt> during the creation of this documentation,
+	and it is therefore unlikely to hit mainline before v4.14.
+	Kudos to Lance Roy, Will Deacon, Peter Zijlstra, and
+	Jonathan Cameron for asking questions that sensitized me
+	to the rather elaborate sequence of events that demonstrate
+	the need for this memory barrier.
+</font></td></tr>
+<tr><td>&nbsp;</td></tr>
+</table>
+
+<p>Tree RCU's grace--period memory-ordering guarantees rely most
+heavily on the <tt>rcu_node</tt> structure's <tt>-&gt;lock</tt>
+field, so much so that it is necessary to abbreviate this pattern
+in the diagrams in the next section.
+For example, consider the <tt>rcu_prepare_for_idle()</tt> function
+shown below, which is one of several functions that enforce ordering
+of newly arrived RCU callbacks against future grace periods:
+
+<pre>
+ 1 static void rcu_prepare_for_idle(void)
+ 2 {
+ 3   bool needwake;
+ 4   struct rcu_data *rdp;
+ 5   struct rcu_dynticks *rdtp = this_cpu_ptr(&amp;rcu_dynticks);
+ 6   struct rcu_node *rnp;
+ 7   struct rcu_state *rsp;
+ 8   int tne;
+ 9
+10   if (IS_ENABLED(CONFIG_RCU_NOCB_CPU_ALL) ||
+11       rcu_is_nocb_cpu(smp_processor_id()))
+12     return;
+13   tne = READ_ONCE(tick_nohz_active);
+14   if (tne != rdtp-&gt;tick_nohz_enabled_snap) {
+15     if (rcu_cpu_has_callbacks(NULL))
+16       invoke_rcu_core();
+17     rdtp-&gt;tick_nohz_enabled_snap = tne;
+18     return;
+19   }
+20   if (!tne)
+21     return;
+22   if (rdtp-&gt;all_lazy &amp;&amp;
+23       rdtp-&gt;nonlazy_posted != rdtp-&gt;nonlazy_posted_snap) {
+24     rdtp-&gt;all_lazy = false;
+25     rdtp-&gt;nonlazy_posted_snap = rdtp-&gt;nonlazy_posted;
+26     invoke_rcu_core();
+27     return;
+28   }
+29   if (rdtp-&gt;last_accelerate == jiffies)
+30     return;
+31   rdtp-&gt;last_accelerate = jiffies;
+32   for_each_rcu_flavor(rsp) {
+33     rdp = this_cpu_ptr(rsp-&gt;rda);
+34     if (rcu_segcblist_pend_cbs(&amp;rdp-&gt;cblist))
+35       continue;
+36     rnp = rdp-&gt;mynode;
+37     raw_spin_lock_rcu_node(rnp);
+38     needwake = rcu_accelerate_cbs(rsp, rnp, rdp);
+39     raw_spin_unlock_rcu_node(rnp);
+40     if (needwake)
+41       rcu_gp_kthread_wake(rsp);
+42   }
+43 }
+</pre>
+
+<p>But the only part of <tt>rcu_prepare_for_idle()</tt> that really
+matters for this discussion are lines&nbsp;37&ndash;39.
+We will therefore abbreviate this function as follows:
+
+</p><p><img src="rcu_node-lock.svg" alt="rcu_node-lock.svg">
+
+<p>The box represents the <tt>rcu_node</tt> structure's <tt>-&gt;lock</tt>
+critical section, with the double line on top representing the additional
+<tt>smp_mb__after_unlock_lock()</tt>.
+
+<h3><a name="Tree RCU Grace Period Memory Ordering Components">
+Tree RCU Grace Period Memory Ordering Components</a></h3>
+
+<p>Tree RCU's grace-period memory-ordering guarantee is provided by
+a number of RCU components:
+
+<ol>
+<li>	<a href="#Callback Registry">Callback Registry</a>
+<li>	<a href="#Grace-Period Initialization">Grace-Period Initialization</a>
+<li>	<a href="#Self-Reported Quiescent States">
+	Self-Reported Quiescent States</a>
+<li>	<a href="#Dynamic Tick Interface">Dynamic Tick Interface</a>
+<li>	<a href="#CPU-Hotplug Interface">CPU-Hotplug Interface</a>
+<li>	<a href="Forcing Quiescent States">Forcing Quiescent States</a>
+<li>	<a href="Grace-Period Cleanup">Grace-Period Cleanup</a>
+<li>	<a href="Callback Invocation">Callback Invocation</a>
+</ol>
+
+<p>Each of the following section looks at the corresponding component
+in detail.
+
+<h4><a name="Callback Registry">Callback Registry</a></h4>
+
+<p>If RCU's grace-period guarantee is to mean anything at all, any
+access that happens before a given invocation of <tt>call_rcu()</tt>
+must also happen before the corresponding grace period.
+The implementation of this portion of RCU's grace period guarantee
+is shown in the following figure:
+
+</p><p><img src="TreeRCU-callback-registry.svg" alt="TreeRCU-callback-registry.svg">
+
+<p>Because <tt>call_rcu()</tt> normally acts only on CPU-local state,
+it provides no ordering guarantees, either for itself or for
+phase one of the update (which again will usually be removal of
+an element from an RCU-protected data structure).
+It simply enqueues the <tt>rcu_head</tt> structure on a per-CPU list,
+which cannot become associated with a grace period until a later
+call to <tt>rcu_accelerate_cbs()</tt>, as shown in the diagram above.
+
+<p>One set of code paths shown on the left invokes
+<tt>rcu_accelerate_cbs()</tt> via
+<tt>note_gp_changes()</tt>, either directly from <tt>call_rcu()</tt> (if
+the current CPU is inundated with queued <tt>rcu_head</tt> structures)
+or more likely from an <tt>RCU_SOFTIRQ</tt> handler.
+Another code path in the middle is taken only in kernels built with
+<tt>CONFIG_RCU_FAST_NO_HZ=y</tt>, which invokes
+<tt>rcu_accelerate_cbs()</tt> via <tt>rcu_prepare_for_idle()</tt>.
+The final code path on the right is taken only in kernels built with
+<tt>CONFIG_HOTPLUG_CPU=y</tt>, which invokes
+<tt>rcu_accelerate_cbs()</tt> via
+<tt>rcu_advance_cbs()</tt>, <tt>rcu_migrate_callbacks</tt>,
+<tt>rcutree_migrate_callbacks()</tt>, and <tt>takedown_cpu()</tt>,
+which in turn is invoked on a surviving CPU after the outgoing
+CPU has been completely offlined.
+
+<p>There are a few other code paths within grace-period processing
+that opportunistically invoke <tt>rcu_accelerate_cbs()</tt>.
+However, either way, all of the CPU's recently queued <tt>rcu_head</tt>
+structures are associated with a future grace-period number under
+the protection of the CPU's lead <tt>rcu_node</tt> structure's
+<tt>-&gt;lock</tt>.
+In all cases, there is full ordering against any prior critical section
+for that same <tt>rcu_node</tt> structure's <tt>-&gt;lock</tt>, and
+also full ordering against any of the current task's or CPU's prior critical
+sections for any <tt>rcu_node</tt> structure's <tt>-&gt;lock</tt>.
+
+<p>The next section will show how this ordering ensures that any
+accesses prior to the <tt>call_rcu()</tt> (particularly including phase
+one of the update)
+happen before the start of the corresponding grace period.
+
+<table>
+<tr><th>&nbsp;</th></tr>
+<tr><th align="left">Quick Quiz:</th></tr>
+<tr><td>
+	But what about <tt>synchronize_rcu()</tt>?
+</td></tr>
+<tr><th align="left">Answer:</th></tr>
+<tr><td bgcolor="#ffffff"><font color="ffffff">
+	The <tt>synchronize_rcu()</tt> passes <tt>call_rcu()</tt>
+	to <tt>wait_rcu_gp()</tt>, which invokes it.
+	So either way, it eventually comes down to <tt>call_rcu()</tt>.
+</font></td></tr>
+<tr><td>&nbsp;</td></tr>
+</table>
+
+<h4><a name="Grace-Period Initialization">Grace-Period Initialization</a></h4>
+
+<p>Grace-period initialization is carried out by
+the grace-period kernel thread, which makes several passes over the
+<tt>rcu_node</tt> tree within the <tt>rcu_gp_init()</tt> function.
+This means that showing the full flow of ordering through the
+grace-period computation will require duplicating this tree.
+If you find this confusing, please note that the state of the
+<tt>rcu_node</tt> changes over time, just like Heraclitus's river.
+However, to keep the <tt>rcu_node</tt> river tractable, the
+grace-period kernel thread's traversals are presented in multiple
+parts, starting in this section with the various phases of
+grace-period initialization.
+
+<p>The first ordering-related grace-period initialization action is to
+advance the <tt>rcu_state</tt> structure's <tt>-&gt;gp_seq</tt>
+grace-period-number counter, as shown below:
+
+</p><p><img src="TreeRCU-gp-init-1.svg" alt="TreeRCU-gp-init-1.svg" width="75%">
+
+<p>The actual increment is carried out using <tt>smp_store_release()</tt>,
+which helps reject false-positive RCU CPU stall detection.
+Note that only the root <tt>rcu_node</tt> structure is touched.
+
+<p>The first pass through the <tt>rcu_node</tt> tree updates bitmasks
+based on CPUs having come online or gone offline since the start of
+the previous grace period.
+In the common case where the number of online CPUs for this <tt>rcu_node</tt>
+structure has not transitioned to or from zero,
+this pass will scan only the leaf <tt>rcu_node</tt> structures.
+However, if the number of online CPUs for a given leaf <tt>rcu_node</tt>
+structure has transitioned from zero,
+<tt>rcu_init_new_rnp()</tt> will be invoked for the first incoming CPU.
+Similarly, if the number of online CPUs for a given leaf <tt>rcu_node</tt>
+structure has transitioned to zero,
+<tt>rcu_cleanup_dead_rnp()</tt> will be invoked for the last outgoing CPU.
+The diagram below shows the path of ordering if the leftmost
+<tt>rcu_node</tt> structure onlines its first CPU and if the next
+<tt>rcu_node</tt> structure has no online CPUs
+(or, alternatively if the leftmost <tt>rcu_node</tt> structure offlines
+its last CPU and if the next <tt>rcu_node</tt> structure has no online CPUs).
+
+</p><p><img src="TreeRCU-gp-init-2.svg" alt="TreeRCU-gp-init-1.svg" width="75%">
+
+<p>The final <tt>rcu_gp_init()</tt> pass through the <tt>rcu_node</tt>
+tree traverses breadth-first, setting each <tt>rcu_node</tt> structure's
+<tt>-&gt;gp_seq</tt> field to the newly advanced value from the
+<tt>rcu_state</tt> structure, as shown in the following diagram.
+
+</p><p><img src="TreeRCU-gp-init-3.svg" alt="TreeRCU-gp-init-1.svg" width="75%">
+
+<p>This change will also cause each CPU's next call to
+<tt>__note_gp_changes()</tt>
+to notice that a new grace period has started, as described in the next
+section.
+But because the grace-period kthread started the grace period at the
+root (with the advancing of the <tt>rcu_state</tt> structure's
+<tt>-&gt;gp_seq</tt> field) before setting each leaf <tt>rcu_node</tt>
+structure's <tt>-&gt;gp_seq</tt> field, each CPU's observation of
+the start of the grace period will happen after the actual start
+of the grace period.
+
+<table>
+<tr><th>&nbsp;</th></tr>
+<tr><th align="left">Quick Quiz:</th></tr>
+<tr><td>
+	But what about the CPU that started the grace period?
+	Why wouldn't it see the start of the grace period right when
+	it started that grace period?
+</td></tr>
+<tr><th align="left">Answer:</th></tr>
+<tr><td bgcolor="#ffffff"><font color="ffffff">
+	In some deep philosophical and overly anthromorphized
+	sense, yes, the CPU starting the grace period is immediately
+	aware of having done so.
+	However, if we instead assume that RCU is not self-aware,
+	then even the CPU starting the grace period does not really
+	become aware of the start of this grace period until its
+	first call to <tt>__note_gp_changes()</tt>.
+	On the other hand, this CPU potentially gets early notification
+	because it invokes <tt>__note_gp_changes()</tt> during its
+	last <tt>rcu_gp_init()</tt> pass through its leaf
+	<tt>rcu_node</tt> structure.
+</font></td></tr>
+<tr><td>&nbsp;</td></tr>
+</table>
+
+<h4><a name="Self-Reported Quiescent States">
+Self-Reported Quiescent States</a></h4>
+
+<p>When all entities that might block the grace period have reported
+quiescent states (or as described in a later section, had quiescent
+states reported on their behalf), the grace period can end.
+Online non-idle CPUs report their own quiescent states, as shown
+in the following diagram:
+
+</p><p><img src="TreeRCU-qs.svg" alt="TreeRCU-qs.svg" width="75%">
+
+<p>This is for the last CPU to report a quiescent state, which signals
+the end of the grace period.
+Earlier quiescent states would push up the <tt>rcu_node</tt> tree
+only until they encountered an <tt>rcu_node</tt> structure that
+is waiting for additional quiescent states.
+However, ordering is nevertheless preserved because some later quiescent
+state will acquire that <tt>rcu_node</tt> structure's <tt>-&gt;lock</tt>.
+
+<p>Any number of events can lead up to a CPU invoking
+<tt>note_gp_changes</tt> (or alternatively, directly invoking
+<tt>__note_gp_changes()</tt>), at which point that CPU will notice
+the start of a new grace period while holding its leaf
+<tt>rcu_node</tt> lock.
+Therefore, all execution shown in this diagram happens after the
+start of the grace period.
+In addition, this CPU will consider any RCU read-side critical
+section that started before the invocation of <tt>__note_gp_changes()</tt>
+to have started before the grace period, and thus a critical
+section that the grace period must wait on.
+
+<table>
+<tr><th>&nbsp;</th></tr>
+<tr><th align="left">Quick Quiz:</th></tr>
+<tr><td>
+	But a RCU read-side critical section might have started
+	after the beginning of the grace period
+	(the advancing of <tt>-&gt;gp_seq</tt> from earlier), so why should
+	the grace period wait on such a critical section?
+</td></tr>
+<tr><th align="left">Answer:</th></tr>
+<tr><td bgcolor="#ffffff"><font color="ffffff">
+	It is indeed not necessary for the grace period to wait on such
+	a critical section.
+	However, it is permissible to wait on it.
+	And it is furthermore important to wait on it, as this
+	lazy approach is far more scalable than a &ldquo;big bang&rdquo;
+	all-at-once grace-period start could possibly be.
+</font></td></tr>
+<tr><td>&nbsp;</td></tr>
+</table>
+
+<p>If the CPU does a context switch, a quiescent state will be
+noted by <tt>rcu_node_context_switch()</tt> on the left.
+On the other hand, if the CPU takes a scheduler-clock interrupt
+while executing in usermode, a quiescent state will be noted by
+<tt>rcu_sched_clock_irq()</tt> on the right.
+Either way, the passage through a quiescent state will be noted
+in a per-CPU variable.
+
+<p>The next time an <tt>RCU_SOFTIRQ</tt> handler executes on
+this CPU (for example, after the next scheduler-clock
+interrupt), <tt>rcu_core()</tt> will invoke
+<tt>rcu_check_quiescent_state()</tt>, which will notice the
+recorded quiescent state, and invoke
+<tt>rcu_report_qs_rdp()</tt>.
+If <tt>rcu_report_qs_rdp()</tt> verifies that the quiescent state
+really does apply to the current grace period, it invokes
+<tt>rcu_report_rnp()</tt> which traverses up the <tt>rcu_node</tt>
+tree as shown at the bottom of the diagram, clearing bits from
+each <tt>rcu_node</tt> structure's <tt>-&gt;qsmask</tt> field,
+and propagating up the tree when the result is zero.
+
+<p>Note that traversal passes upwards out of a given <tt>rcu_node</tt>
+structure only if the current CPU is reporting the last quiescent
+state for the subtree headed by that <tt>rcu_node</tt> structure.
+A key point is that if a CPU's traversal stops at a given <tt>rcu_node</tt>
+structure, then there will be a later traversal by another CPU
+(or perhaps the same one) that proceeds upwards
+from that point, and the <tt>rcu_node</tt> <tt>-&gt;lock</tt>
+guarantees that the first CPU's quiescent state happens before the
+remainder of the second CPU's traversal.
+Applying this line of thought repeatedly shows that all CPUs'
+quiescent states happen before the last CPU traverses through
+the root <tt>rcu_node</tt> structure, the &ldquo;last CPU&rdquo;
+being the one that clears the last bit in the root <tt>rcu_node</tt>
+structure's <tt>-&gt;qsmask</tt> field.
+
+<h4><a name="Dynamic Tick Interface">Dynamic Tick Interface</a></h4>
+
+<p>Due to energy-efficiency considerations, RCU is forbidden from
+disturbing idle CPUs.
+CPUs are therefore required to notify RCU when entering or leaving idle
+state, which they do via fully ordered value-returning atomic operations
+on a per-CPU variable.
+The ordering effects are as shown below:
+
+</p><p><img src="TreeRCU-dyntick.svg" alt="TreeRCU-dyntick.svg" width="50%">
+
+<p>The RCU grace-period kernel thread samples the per-CPU idleness
+variable while holding the corresponding CPU's leaf <tt>rcu_node</tt>
+structure's <tt>-&gt;lock</tt>.
+This means that any RCU read-side critical sections that precede the
+idle period (the oval near the top of the diagram above) will happen
+before the end of the current grace period.
+Similarly, the beginning of the current grace period will happen before
+any RCU read-side critical sections that follow the
+idle period (the oval near the bottom of the diagram above).
+
+<p>Plumbing this into the full grace-period execution is described
+<a href="#Forcing Quiescent States">below</a>.
+
+<h4><a name="CPU-Hotplug Interface">CPU-Hotplug Interface</a></h4>
+
+<p>RCU is also forbidden from disturbing offline CPUs, which might well
+be powered off and removed from the system completely.
+CPUs are therefore required to notify RCU of their comings and goings
+as part of the corresponding CPU hotplug operations.
+The ordering effects are shown below:
+
+</p><p><img src="TreeRCU-hotplug.svg" alt="TreeRCU-hotplug.svg" width="50%">
+
+<p>Because CPU hotplug operations are much less frequent than idle transitions,
+they are heavier weight, and thus acquire the CPU's leaf <tt>rcu_node</tt>
+structure's <tt>-&gt;lock</tt> and update this structure's
+<tt>-&gt;qsmaskinitnext</tt>.
+The RCU grace-period kernel thread samples this mask to detect CPUs
+having gone offline since the beginning of this grace period.
+
+<p>Plumbing this into the full grace-period execution is described
+<a href="#Forcing Quiescent States">below</a>.
+
+<h4><a name="Forcing Quiescent States">Forcing Quiescent States</a></h4>
+
+<p>As noted above, idle and offline CPUs cannot report their own
+quiescent states, and therefore the grace-period kernel thread
+must do the reporting on their behalf.
+This process is called &ldquo;forcing quiescent states&rdquo;, it is
+repeated every few jiffies, and its ordering effects are shown below:
+
+</p><p><img src="TreeRCU-gp-fqs.svg" alt="TreeRCU-gp-fqs.svg" width="100%">
+
+<p>Each pass of quiescent state forcing is guaranteed to traverse the
+leaf <tt>rcu_node</tt> structures, and if there are no new quiescent
+states due to recently idled and/or offlined CPUs, then only the
+leaves are traversed.
+However, if there is a newly offlined CPU as illustrated on the left
+or a newly idled CPU as illustrated on the right, the corresponding
+quiescent state will be driven up towards the root.
+As with self-reported quiescent states, the upwards driving stops
+once it reaches an <tt>rcu_node</tt> structure that has quiescent
+states outstanding from other CPUs.
+
+<table>
+<tr><th>&nbsp;</th></tr>
+<tr><th align="left">Quick Quiz:</th></tr>
+<tr><td>
+	The leftmost drive to root stopped before it reached
+	the root <tt>rcu_node</tt> structure, which means that
+	there are still CPUs subordinate to that structure on
+	which the current grace period is waiting.
+	Given that, how is it possible that the rightmost drive
+	to root ended the grace period?
+</td></tr>
+<tr><th align="left">Answer:</th></tr>
+<tr><td bgcolor="#ffffff"><font color="ffffff">
+	Good analysis!
+	It is in fact impossible in the absence of bugs in RCU.
+	But this diagram is complex enough as it is, so simplicity
+	overrode accuracy.
+	You can think of it as poetic license, or you can think of
+	it as misdirection that is resolved in the
+	<a href="#Putting It All Together">stitched-together diagram</a>.
+</font></td></tr>
+<tr><td>&nbsp;</td></tr>
+</table>
+
+<h4><a name="Grace-Period Cleanup">Grace-Period Cleanup</a></h4>
+
+<p>Grace-period cleanup first scans the <tt>rcu_node</tt> tree
+breadth-first advancing all the <tt>-&gt;gp_seq</tt> fields, then it
+advances the <tt>rcu_state</tt> structure's <tt>-&gt;gp_seq</tt> field.
+The ordering effects are shown below:
+
+</p><p><img src="TreeRCU-gp-cleanup.svg" alt="TreeRCU-gp-cleanup.svg" width="75%">
+
+<p>As indicated by the oval at the bottom of the diagram, once
+grace-period cleanup is complete, the next grace period can begin.
+
+<table>
+<tr><th>&nbsp;</th></tr>
+<tr><th align="left">Quick Quiz:</th></tr>
+<tr><td>
+	But when precisely does the grace period end?
+</td></tr>
+<tr><th align="left">Answer:</th></tr>
+<tr><td bgcolor="#ffffff"><font color="ffffff">
+	There is no useful single point at which the grace period
+	can be said to end.
+	The earliest reasonable candidate is as soon as the last
+	CPU has reported its quiescent state, but it may be some
+	milliseconds before RCU becomes aware of this.
+	The latest reasonable candidate is once the <tt>rcu_state</tt>
+	structure's <tt>-&gt;gp_seq</tt> field has been updated,
+	but it is quite possible that some CPUs have already completed
+	phase two of their updates by that time.
+	In short, if you are going to work with RCU, you need to
+	learn to embrace uncertainty.
+</font></td></tr>
+<tr><td>&nbsp;</td></tr>
+</table>
+
+
+<h4><a name="Callback Invocation">Callback Invocation</a></h4>
+
+<p>Once a given CPU's leaf <tt>rcu_node</tt> structure's
+<tt>-&gt;gp_seq</tt> field has been updated, that CPU can begin
+invoking its RCU callbacks that were waiting for this grace period
+to end.
+These callbacks are identified by <tt>rcu_advance_cbs()</tt>,
+which is usually invoked by <tt>__note_gp_changes()</tt>.
+As shown in the diagram below, this invocation can be triggered by
+the scheduling-clock interrupt (<tt>rcu_sched_clock_irq()</tt> on
+the left) or by idle entry (<tt>rcu_cleanup_after_idle()</tt> on
+the right, but only for kernels build with
+<tt>CONFIG_RCU_FAST_NO_HZ=y</tt>).
+Either way, <tt>RCU_SOFTIRQ</tt> is raised, which results in
+<tt>rcu_do_batch()</tt> invoking the callbacks, which in turn
+allows those callbacks to carry out (either directly or indirectly
+via wakeup) the needed phase-two processing for each update.
+
+</p><p><img src="TreeRCU-callback-invocation.svg" alt="TreeRCU-callback-invocation.svg" width="60%">
+
+<p>Please note that callback invocation can also be prompted by any
+number of corner-case code paths, for example, when a CPU notes that
+it has excessive numbers of callbacks queued.
+In all cases, the CPU acquires its leaf <tt>rcu_node</tt> structure's
+<tt>-&gt;lock</tt> before invoking callbacks, which preserves the
+required ordering against the newly completed grace period.
+
+<p>However, if the callback function communicates to other CPUs,
+for example, doing a wakeup, then it is that function's responsibility
+to maintain ordering.
+For example, if the callback function wakes up a task that runs on
+some other CPU, proper ordering must in place in both the callback
+function and the task being awakened.
+To see why this is important, consider the top half of the
+<a href="#Grace-Period Cleanup">grace-period cleanup</a> diagram.
+The callback might be running on a CPU corresponding to the leftmost
+leaf <tt>rcu_node</tt> structure, and awaken a task that is to run on
+a CPU corresponding to the rightmost leaf <tt>rcu_node</tt> structure,
+and the grace-period kernel thread might not yet have reached the
+rightmost leaf.
+In this case, the grace period's memory ordering might not yet have
+reached that CPU, so again the callback function and the awakened
+task must supply proper ordering.
+
+<h3><a name="Putting It All Together">Putting It All Together</a></h3>
+
+<p>A stitched-together diagram is
+<a href="Tree-RCU-Diagram.html">here</a>.
+
+<h3><a name="Legal Statement">
+Legal Statement</a></h3>
+
+<p>This work represents the view of the author and does not necessarily
+represent the view of IBM.
+
+</p><p>Linux is a registered trademark of Linus Torvalds.
+
+</p><p>Other company, product, and service names may be trademarks or
+service marks of others.
+
+</body></html>

Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst

@@ -1,624 +0,0 @@
-======================================================
-A Tour Through TREE_RCU's Grace-Period Memory Ordering
-======================================================
-
-August 8, 2017
-
-This article was contributed by Paul E. McKenney
-
-Introduction
-============
-
-This document gives a rough visual overview of how Tree RCU's
-grace-period memory ordering guarantee is provided.
-
-What Is Tree RCU's Grace Period Memory Ordering Guarantee?
-==========================================================
-
-RCU grace periods provide extremely strong memory-ordering guarantees
-for non-idle non-offline code.
-Any code that happens after the end of a given RCU grace period is guaranteed
-to see the effects of all accesses prior to the beginning of that grace
-period that are within RCU read-side critical sections.
-Similarly, any code that happens before the beginning of a given RCU grace
-period is guaranteed to see the effects of all accesses following the end
-of that grace period that are within RCU read-side critical sections.
-
-Note well that RCU-sched read-side critical sections include any region
-of code for which preemption is disabled.
-Given that each individual machine instruction can be thought of as
-an extremely small region of preemption-disabled code, one can think of
-``synchronize_rcu()`` as ``smp_mb()`` on steroids.
-
-RCU updaters use this guarantee by splitting their updates into
-two phases, one of which is executed before the grace period and
-the other of which is executed after the grace period.
-In the most common use case, phase one removes an element from
-a linked RCU-protected data structure, and phase two frees that element.
-For this to work, any readers that have witnessed state prior to the
-phase-one update (in the common case, removal) must not witness state
-following the phase-two update (in the common case, freeing).
-
-The RCU implementation provides this guarantee using a network
-of lock-based critical sections, memory barriers, and per-CPU
-processing, as is described in the following sections.
-
-Tree RCU Grace Period Memory Ordering Building Blocks
-=====================================================
-
-The workhorse for RCU's grace-period memory ordering is the
-critical section for the ``rcu_node`` structure's
-``->lock``. These critical sections use helper functions for lock
-acquisition, including ``raw_spin_lock_rcu_node()``,
-``raw_spin_lock_irq_rcu_node()``, and ``raw_spin_lock_irqsave_rcu_node()``.
-Their lock-release counterparts are ``raw_spin_unlock_rcu_node()``,
-``raw_spin_unlock_irq_rcu_node()``, and
-``raw_spin_unlock_irqrestore_rcu_node()``, respectively.
-For completeness, a ``raw_spin_trylock_rcu_node()`` is also provided.
-The key point is that the lock-acquisition functions, including
-``raw_spin_trylock_rcu_node()``, all invoke ``smp_mb__after_unlock_lock()``
-immediately after successful acquisition of the lock.
-
-Therefore, for any given ``rcu_node`` structure, any access
-happening before one of the above lock-release functions will be seen
-by all CPUs as happening before any access happening after a later
-one of the above lock-acquisition functions.
-Furthermore, any access happening before one of the
-above lock-release function on any given CPU will be seen by all
-CPUs as happening before any access happening after a later one
-of the above lock-acquisition functions executing on that same CPU,
-even if the lock-release and lock-acquisition functions are operating
-on different ``rcu_node`` structures.
-Tree RCU uses these two ordering guarantees to form an ordering
-network among all CPUs that were in any way involved in the grace
-period, including any CPUs that came online or went offline during
-the grace period in question.
-
-The following litmus test exhibits the ordering effects of these
-lock-acquisition and lock-release functions::
-
-    1 int x, y, z;
-    2
-    3 void task0(void)
-    4 {
-    5   raw_spin_lock_rcu_node(rnp);
-    6   WRITE_ONCE(x, 1);
-    7   r1 = READ_ONCE(y);
-    8   raw_spin_unlock_rcu_node(rnp);
-    9 }
-   10
-   11 void task1(void)
-   12 {
-   13   raw_spin_lock_rcu_node(rnp);
-   14   WRITE_ONCE(y, 1);
-   15   r2 = READ_ONCE(z);
-   16   raw_spin_unlock_rcu_node(rnp);
-   17 }
-   18
-   19 void task2(void)
-   20 {
-   21   WRITE_ONCE(z, 1);
-   22   smp_mb();
-   23   r3 = READ_ONCE(x);
-   24 }
-   25
-   26 WARN_ON(r1 == 0 && r2 == 0 && r3 == 0);
-
-The ``WARN_ON()`` is evaluated at “the end of time”,
-after all changes have propagated throughout the system.
-Without the ``smp_mb__after_unlock_lock()`` provided by the
-acquisition functions, this ``WARN_ON()`` could trigger, for example
-on PowerPC.
-The ``smp_mb__after_unlock_lock()`` invocations prevent this
-``WARN_ON()`` from triggering.
-
-This approach must be extended to include idle CPUs, which need
-RCU's grace-period memory ordering guarantee to extend to any
-RCU read-side critical sections preceding and following the current
-idle sojourn.
-This case is handled by calls to the strongly ordered
-``atomic_add_return()`` read-modify-write atomic operation that
-is invoked within ``rcu_dynticks_eqs_enter()`` at idle-entry
-time and within ``rcu_dynticks_eqs_exit()`` at idle-exit time.
-The grace-period kthread invokes ``rcu_dynticks_snap()`` and
-``rcu_dynticks_in_eqs_since()`` (both of which invoke
-an ``atomic_add_return()`` of zero) to detect idle CPUs.
-
-+-----------------------------------------------------------------------+
-| **Quick Quiz**:                                                       |
-+-----------------------------------------------------------------------+
-| But what about CPUs that remain offline for the entire grace period?  |
-+-----------------------------------------------------------------------+
-| **Answer**:                                                           |
-+-----------------------------------------------------------------------+
-| Such CPUs will be offline at the beginning of the grace period, so    |
-| the grace period won't expect quiescent states from them. Races       |
-| between grace-period start and CPU-hotplug operations are mediated    |
-| by the CPU's leaf ``rcu_node`` structure's ``->lock`` as described    |
-| above.                                                                |
-+-----------------------------------------------------------------------+
-
-The approach must be extended to handle one final case, that of waking a
-task blocked in ``synchronize_rcu()``. This task might be affinitied to
-a CPU that is not yet aware that the grace period has ended, and thus
-might not yet be subject to the grace period's memory ordering.
-Therefore, there is an ``smp_mb()`` after the return from
-``wait_for_completion()`` in the ``synchronize_rcu()`` code path.
-
-+-----------------------------------------------------------------------+
-| **Quick Quiz**:                                                       |
-+-----------------------------------------------------------------------+
-| What? Where??? I don't see any ``smp_mb()`` after the return from     |
-| ``wait_for_completion()``!!!                                          |
-+-----------------------------------------------------------------------+
-| **Answer**:                                                           |
-+-----------------------------------------------------------------------+
-| That would be because I spotted the need for that ``smp_mb()`` during |
-| the creation of this documentation, and it is therefore unlikely to   |
-| hit mainline before v4.14. Kudos to Lance Roy, Will Deacon, Peter     |
-| Zijlstra, and Jonathan Cameron for asking questions that sensitized   |
-| me to the rather elaborate sequence of events that demonstrate the    |
-| need for this memory barrier.                                         |
-+-----------------------------------------------------------------------+
-
-Tree RCU's grace--period memory-ordering guarantees rely most heavily on
-the ``rcu_node`` structure's ``->lock`` field, so much so that it is
-necessary to abbreviate this pattern in the diagrams in the next
-section. For example, consider the ``rcu_prepare_for_idle()`` function
-shown below, which is one of several functions that enforce ordering of
-newly arrived RCU callbacks against future grace periods:
-
-::
-
-    1 static void rcu_prepare_for_idle(void)
-    2 {
-    3   bool needwake;
-    4   struct rcu_data *rdp;
-    5   struct rcu_dynticks *rdtp = this_cpu_ptr(&rcu_dynticks);
-    6   struct rcu_node *rnp;
-    7   struct rcu_state *rsp;
-    8   int tne;
-    9
-   10   if (IS_ENABLED(CONFIG_RCU_NOCB_CPU_ALL) ||
-   11       rcu_is_nocb_cpu(smp_processor_id()))
-   12     return;
-   13   tne = READ_ONCE(tick_nohz_active);
-   14   if (tne != rdtp->tick_nohz_enabled_snap) {
-   15     if (rcu_cpu_has_callbacks(NULL))
-   16       invoke_rcu_core();
-   17     rdtp->tick_nohz_enabled_snap = tne;
-   18     return;
-   19   }
-   20   if (!tne)
-   21     return;
-   22   if (rdtp->all_lazy &&
-   23       rdtp->nonlazy_posted != rdtp->nonlazy_posted_snap) {
-   24     rdtp->all_lazy = false;
-   25     rdtp->nonlazy_posted_snap = rdtp->nonlazy_posted;
-   26     invoke_rcu_core();
-   27     return;
-   28   }
-   29   if (rdtp->last_accelerate == jiffies)
-   30     return;
-   31   rdtp->last_accelerate = jiffies;
-   32   for_each_rcu_flavor(rsp) {
-   33     rdp = this_cpu_ptr(rsp->rda);
-   34     if (rcu_segcblist_pend_cbs(&rdp->cblist))
-   35       continue;
-   36     rnp = rdp->mynode;
-   37     raw_spin_lock_rcu_node(rnp);
-   38     needwake = rcu_accelerate_cbs(rsp, rnp, rdp);
-   39     raw_spin_unlock_rcu_node(rnp);
-   40     if (needwake)
-   41       rcu_gp_kthread_wake(rsp);
-   42   }
-   43 }
-
-But the only part of ``rcu_prepare_for_idle()`` that really matters for
-this discussion are lines 37–39. We will therefore abbreviate this
-function as follows:
-
-.. kernel-figure:: rcu_node-lock.svg
-
-The box represents the ``rcu_node`` structure's ``->lock`` critical
-section, with the double line on top representing the additional
-``smp_mb__after_unlock_lock()``.
-
-Tree RCU Grace Period Memory Ordering Components
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Tree RCU's grace-period memory-ordering guarantee is provided by a
-number of RCU components:
-
-#. `Callback Registry`_
-#. `Grace-Period Initialization`_
-#. `Self-Reported Quiescent States`_
-#. `Dynamic Tick Interface`_
-#. `CPU-Hotplug Interface`_
-#. `Forcing Quiescent States`_
-#. `Grace-Period Cleanup`_
-#. `Callback Invocation`_
-
-Each of the following section looks at the corresponding component in
-detail.
-
-Callback Registry
-^^^^^^^^^^^^^^^^^
-
-If RCU's grace-period guarantee is to mean anything at all, any access
-that happens before a given invocation of ``call_rcu()`` must also
-happen before the corresponding grace period. The implementation of this
-portion of RCU's grace period guarantee is shown in the following
-figure:
-
-.. kernel-figure:: TreeRCU-callback-registry.svg
-
-Because ``call_rcu()`` normally acts only on CPU-local state, it
-provides no ordering guarantees, either for itself or for phase one of
-the update (which again will usually be removal of an element from an
-RCU-protected data structure). It simply enqueues the ``rcu_head``
-structure on a per-CPU list, which cannot become associated with a grace
-period until a later call to ``rcu_accelerate_cbs()``, as shown in the
-diagram above.
-
-One set of code paths shown on the left invokes ``rcu_accelerate_cbs()``
-via ``note_gp_changes()``, either directly from ``call_rcu()`` (if the
-current CPU is inundated with queued ``rcu_head`` structures) or more
-likely from an ``RCU_SOFTIRQ`` handler. Another code path in the middle
-is taken only in kernels built with ``CONFIG_RCU_FAST_NO_HZ=y``, which
-invokes ``rcu_accelerate_cbs()`` via ``rcu_prepare_for_idle()``. The
-final code path on the right is taken only in kernels built with
-``CONFIG_HOTPLUG_CPU=y``, which invokes ``rcu_accelerate_cbs()`` via
-``rcu_advance_cbs()``, ``rcu_migrate_callbacks``,
-``rcutree_migrate_callbacks()``, and ``takedown_cpu()``, which in turn
-is invoked on a surviving CPU after the outgoing CPU has been completely
-offlined.
-
-There are a few other code paths within grace-period processing that
-opportunistically invoke ``rcu_accelerate_cbs()``. However, either way,
-all of the CPU's recently queued ``rcu_head`` structures are associated
-with a future grace-period number under the protection of the CPU's lead
-``rcu_node`` structure's ``->lock``. In all cases, there is full
-ordering against any prior critical section for that same ``rcu_node``
-structure's ``->lock``, and also full ordering against any of the
-current task's or CPU's prior critical sections for any ``rcu_node``
-structure's ``->lock``.
-
-The next section will show how this ordering ensures that any accesses
-prior to the ``call_rcu()`` (particularly including phase one of the
-update) happen before the start of the corresponding grace period.
-
-+-----------------------------------------------------------------------+
-| **Quick Quiz**:                                                       |
-+-----------------------------------------------------------------------+
-| But what about ``synchronize_rcu()``?                                 |
-+-----------------------------------------------------------------------+
-| **Answer**:                                                           |
-+-----------------------------------------------------------------------+
-| The ``synchronize_rcu()`` passes ``call_rcu()`` to ``wait_rcu_gp()``, |
-| which invokes it. So either way, it eventually comes down to          |
-| ``call_rcu()``.                                                       |
-+-----------------------------------------------------------------------+
-
-Grace-Period Initialization
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Grace-period initialization is carried out by the grace-period kernel
-thread, which makes several passes over the ``rcu_node`` tree within the
-``rcu_gp_init()`` function. This means that showing the full flow of
-ordering through the grace-period computation will require duplicating
-this tree. If you find this confusing, please note that the state of the
-``rcu_node`` changes over time, just like Heraclitus's river. However,
-to keep the ``rcu_node`` river tractable, the grace-period kernel
-thread's traversals are presented in multiple parts, starting in this
-section with the various phases of grace-period initialization.
-
-The first ordering-related grace-period initialization action is to
-advance the ``rcu_state`` structure's ``->gp_seq`` grace-period-number
-counter, as shown below:
-
-.. kernel-figure:: TreeRCU-gp-init-1.svg
-
-The actual increment is carried out using ``smp_store_release()``, which
-helps reject false-positive RCU CPU stall detection. Note that only the
-root ``rcu_node`` structure is touched.
-
-The first pass through the ``rcu_node`` tree updates bitmasks based on
-CPUs having come online or gone offline since the start of the previous
-grace period. In the common case where the number of online CPUs for
-this ``rcu_node`` structure has not transitioned to or from zero, this
-pass will scan only the leaf ``rcu_node`` structures. However, if the
-number of online CPUs for a given leaf ``rcu_node`` structure has
-transitioned from zero, ``rcu_init_new_rnp()`` will be invoked for the
-first incoming CPU. Similarly, if the number of online CPUs for a given
-leaf ``rcu_node`` structure has transitioned to zero,
-``rcu_cleanup_dead_rnp()`` will be invoked for the last outgoing CPU.
-The diagram below shows the path of ordering if the leftmost
-``rcu_node`` structure onlines its first CPU and if the next
-``rcu_node`` structure has no online CPUs (or, alternatively if the
-leftmost ``rcu_node`` structure offlines its last CPU and if the next
-``rcu_node`` structure has no online CPUs).
-
-.. kernel-figure:: TreeRCU-gp-init-1.svg
-
-The final ``rcu_gp_init()`` pass through the ``rcu_node`` tree traverses
-breadth-first, setting each ``rcu_node`` structure's ``->gp_seq`` field
-to the newly advanced value from the ``rcu_state`` structure, as shown
-in the following diagram.
-
-.. kernel-figure:: TreeRCU-gp-init-1.svg
-
-This change will also cause each CPU's next call to
-``__note_gp_changes()`` to notice that a new grace period has started,
-as described in the next section. But because the grace-period kthread
-started the grace period at the root (with the advancing of the
-``rcu_state`` structure's ``->gp_seq`` field) before setting each leaf
-``rcu_node`` structure's ``->gp_seq`` field, each CPU's observation of
-the start of the grace period will happen after the actual start of the
-grace period.
-
-+-----------------------------------------------------------------------+
-| **Quick Quiz**:                                                       |
-+-----------------------------------------------------------------------+
-| But what about the CPU that started the grace period? Why wouldn't it |
-| see the start of the grace period right when it started that grace    |
-| period?                                                               |
-+-----------------------------------------------------------------------+
-| **Answer**:                                                           |
-+-----------------------------------------------------------------------+
-| In some deep philosophical and overly anthromorphized sense, yes, the |
-| CPU starting the grace period is immediately aware of having done so. |
-| However, if we instead assume that RCU is not self-aware, then even   |
-| the CPU starting the grace period does not really become aware of the |
-| start of this grace period until its first call to                    |
-| ``__note_gp_changes()``. On the other hand, this CPU potentially gets |
-| early notification because it invokes ``__note_gp_changes()`` during  |
-| its last ``rcu_gp_init()`` pass through its leaf ``rcu_node``         |
-| structure.                                                            |
-+-----------------------------------------------------------------------+
-
-Self-Reported Quiescent States
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When all entities that might block the grace period have reported
-quiescent states (or as described in a later section, had quiescent
-states reported on their behalf), the grace period can end. Online
-non-idle CPUs report their own quiescent states, as shown in the
-following diagram:
-
-.. kernel-figure:: TreeRCU-qs.svg
-
-This is for the last CPU to report a quiescent state, which signals the
-end of the grace period. Earlier quiescent states would push up the
-``rcu_node`` tree only until they encountered an ``rcu_node`` structure
-that is waiting for additional quiescent states. However, ordering is
-nevertheless preserved because some later quiescent state will acquire
-that ``rcu_node`` structure's ``->lock``.
-
-Any number of events can lead up to a CPU invoking ``note_gp_changes``
-(or alternatively, directly invoking ``__note_gp_changes()``), at which
-point that CPU will notice the start of a new grace period while holding
-its leaf ``rcu_node`` lock. Therefore, all execution shown in this
-diagram happens after the start of the grace period. In addition, this
-CPU will consider any RCU read-side critical section that started before
-the invocation of ``__note_gp_changes()`` to have started before the
-grace period, and thus a critical section that the grace period must
-wait on.
-
-+-----------------------------------------------------------------------+
-| **Quick Quiz**:                                                       |
-+-----------------------------------------------------------------------+
-| But a RCU read-side critical section might have started after the     |
-| beginning of the grace period (the advancing of ``->gp_seq`` from     |
-| earlier), so why should the grace period wait on such a critical      |
-| section?                                                              |
-+-----------------------------------------------------------------------+
-| **Answer**:                                                           |
-+-----------------------------------------------------------------------+
-| It is indeed not necessary for the grace period to wait on such a     |
-| critical section. However, it is permissible to wait on it. And it is |
-| furthermore important to wait on it, as this lazy approach is far     |
-| more scalable than a “big bang” all-at-once grace-period start could  |
-| possibly be.                                                          |
-+-----------------------------------------------------------------------+
-
-If the CPU does a context switch, a quiescent state will be noted by
-``rcu_note_context_switch()`` on the left. On the other hand, if the CPU
-takes a scheduler-clock interrupt while executing in usermode, a
-quiescent state will be noted by ``rcu_sched_clock_irq()`` on the right.
-Either way, the passage through a quiescent state will be noted in a
-per-CPU variable.
-
-The next time an ``RCU_SOFTIRQ`` handler executes on this CPU (for
-example, after the next scheduler-clock interrupt), ``rcu_core()`` will
-invoke ``rcu_check_quiescent_state()``, which will notice the recorded
-quiescent state, and invoke ``rcu_report_qs_rdp()``. If
-``rcu_report_qs_rdp()`` verifies that the quiescent state really does
-apply to the current grace period, it invokes ``rcu_report_rnp()`` which
-traverses up the ``rcu_node`` tree as shown at the bottom of the
-diagram, clearing bits from each ``rcu_node`` structure's ``->qsmask``
-field, and propagating up the tree when the result is zero.
-
-Note that traversal passes upwards out of a given ``rcu_node`` structure
-only if the current CPU is reporting the last quiescent state for the
-subtree headed by that ``rcu_node`` structure. A key point is that if a
-CPU's traversal stops at a given ``rcu_node`` structure, then there will
-be a later traversal by another CPU (or perhaps the same one) that
-proceeds upwards from that point, and the ``rcu_node`` ``->lock``
-guarantees that the first CPU's quiescent state happens before the
-remainder of the second CPU's traversal. Applying this line of thought
-repeatedly shows that all CPUs' quiescent states happen before the last
-CPU traverses through the root ``rcu_node`` structure, the “last CPU”
-being the one that clears the last bit in the root ``rcu_node``
-structure's ``->qsmask`` field.
-
-Dynamic Tick Interface
-^^^^^^^^^^^^^^^^^^^^^^
-
-Due to energy-efficiency considerations, RCU is forbidden from
-disturbing idle CPUs. CPUs are therefore required to notify RCU when
-entering or leaving idle state, which they do via fully ordered
-value-returning atomic operations on a per-CPU variable. The ordering
-effects are as shown below:
-
-.. kernel-figure:: TreeRCU-dyntick.svg
-
-The RCU grace-period kernel thread samples the per-CPU idleness variable
-while holding the corresponding CPU's leaf ``rcu_node`` structure's
-``->lock``. This means that any RCU read-side critical sections that
-precede the idle period (the oval near the top of the diagram above)
-will happen before the end of the current grace period. Similarly, the
-beginning of the current grace period will happen before any RCU
-read-side critical sections that follow the idle period (the oval near
-the bottom of the diagram above).
-
-Plumbing this into the full grace-period execution is described
-`below <#Forcing%20Quiescent%20States>`__.
-
-CPU-Hotplug Interface
-^^^^^^^^^^^^^^^^^^^^^
-
-RCU is also forbidden from disturbing offline CPUs, which might well be
-powered off and removed from the system completely. CPUs are therefore
-required to notify RCU of their comings and goings as part of the
-corresponding CPU hotplug operations. The ordering effects are shown
-below:
-
-.. kernel-figure:: TreeRCU-hotplug.svg
-
-Because CPU hotplug operations are much less frequent than idle
-transitions, they are heavier weight, and thus acquire the CPU's leaf
-``rcu_node`` structure's ``->lock`` and update this structure's
-``->qsmaskinitnext``. The RCU grace-period kernel thread samples this
-mask to detect CPUs having gone offline since the beginning of this
-grace period.
-
-Plumbing this into the full grace-period execution is described
-`below <#Forcing%20Quiescent%20States>`__.
-
-Forcing Quiescent States
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-As noted above, idle and offline CPUs cannot report their own quiescent
-states, and therefore the grace-period kernel thread must do the
-reporting on their behalf. This process is called “forcing quiescent
-states”, it is repeated every few jiffies, and its ordering effects are
-shown below:
-
-.. kernel-figure:: TreeRCU-gp-fqs.svg
-
-Each pass of quiescent state forcing is guaranteed to traverse the leaf
-``rcu_node`` structures, and if there are no new quiescent states due to
-recently idled and/or offlined CPUs, then only the leaves are traversed.
-However, if there is a newly offlined CPU as illustrated on the left or
-a newly idled CPU as illustrated on the right, the corresponding
-quiescent state will be driven up towards the root. As with
-self-reported quiescent states, the upwards driving stops once it
-reaches an ``rcu_node`` structure that has quiescent states outstanding
-from other CPUs.
-
-+-----------------------------------------------------------------------+
-| **Quick Quiz**:                                                       |
-+-----------------------------------------------------------------------+
-| The leftmost drive to root stopped before it reached the root         |
-| ``rcu_node`` structure, which means that there are still CPUs         |
-| subordinate to that structure on which the current grace period is    |
-| waiting. Given that, how is it possible that the rightmost drive to   |
-| root ended the grace period?                                          |
-+-----------------------------------------------------------------------+
-| **Answer**:                                                           |
-+-----------------------------------------------------------------------+
-| Good analysis! It is in fact impossible in the absence of bugs in     |
-| RCU. But this diagram is complex enough as it is, so simplicity       |
-| overrode accuracy. You can think of it as poetic license, or you can  |
-| think of it as misdirection that is resolved in the                   |
-| `stitched-together diagram <#Putting%20It%20All%20Together>`__.       |
-+-----------------------------------------------------------------------+
-
-Grace-Period Cleanup
-^^^^^^^^^^^^^^^^^^^^
-
-Grace-period cleanup first scans the ``rcu_node`` tree breadth-first
-advancing all the ``->gp_seq`` fields, then it advances the
-``rcu_state`` structure's ``->gp_seq`` field. The ordering effects are
-shown below:
-
-.. kernel-figure:: TreeRCU-gp-cleanup.svg
-
-As indicated by the oval at the bottom of the diagram, once grace-period
-cleanup is complete, the next grace period can begin.
-
-+-----------------------------------------------------------------------+
-| **Quick Quiz**:                                                       |
-+-----------------------------------------------------------------------+
-| But when precisely does the grace period end?                         |
-+-----------------------------------------------------------------------+
-| **Answer**:                                                           |
-+-----------------------------------------------------------------------+
-| There is no useful single point at which the grace period can be said |
-| to end. The earliest reasonable candidate is as soon as the last CPU  |
-| has reported its quiescent state, but it may be some milliseconds     |
-| before RCU becomes aware of this. The latest reasonable candidate is  |
-| once the ``rcu_state`` structure's ``->gp_seq`` field has been        |
-| updated, but it is quite possible that some CPUs have already         |
-| completed phase two of their updates by that time. In short, if you   |
-| are going to work with RCU, you need to learn to embrace uncertainty. |
-+-----------------------------------------------------------------------+
-
-Callback Invocation
-^^^^^^^^^^^^^^^^^^^
-
-Once a given CPU's leaf ``rcu_node`` structure's ``->gp_seq`` field has
-been updated, that CPU can begin invoking its RCU callbacks that were
-waiting for this grace period to end. These callbacks are identified by
-``rcu_advance_cbs()``, which is usually invoked by
-``__note_gp_changes()``. As shown in the diagram below, this invocation
-can be triggered by the scheduling-clock interrupt
-(``rcu_sched_clock_irq()`` on the left) or by idle entry
-(``rcu_cleanup_after_idle()`` on the right, but only for kernels build
-with ``CONFIG_RCU_FAST_NO_HZ=y``). Either way, ``RCU_SOFTIRQ`` is
-raised, which results in ``rcu_do_batch()`` invoking the callbacks,
-which in turn allows those callbacks to carry out (either directly or
-indirectly via wakeup) the needed phase-two processing for each update.
-
-.. kernel-figure:: TreeRCU-callback-invocation.svg
-
-Please note that callback invocation can also be prompted by any number
-of corner-case code paths, for example, when a CPU notes that it has
-excessive numbers of callbacks queued. In all cases, the CPU acquires
-its leaf ``rcu_node`` structure's ``->lock`` before invoking callbacks,
-which preserves the required ordering against the newly completed grace
-period.
-
-However, if the callback function communicates to other CPUs, for
-example, doing a wakeup, then it is that function's responsibility to
-maintain ordering. For example, if the callback function wakes up a task
-that runs on some other CPU, proper ordering must in place in both the
-callback function and the task being awakened. To see why this is
-important, consider the top half of the `grace-period
-cleanup <#Grace-Period%20Cleanup>`__ diagram. The callback might be
-running on a CPU corresponding to the leftmost leaf ``rcu_node``
-structure, and awaken a task that is to run on a CPU corresponding to
-the rightmost leaf ``rcu_node`` structure, and the grace-period kernel
-thread might not yet have reached the rightmost leaf. In this case, the
-grace period's memory ordering might not yet have reached that CPU, so
-again the callback function and the awakened task must supply proper
-ordering.
-
-Putting It All Together
-~~~~~~~~~~~~~~~~~~~~~~~
-
-A stitched-together diagram is here:
-
-.. kernel-figure:: TreeRCU-gp.svg
-
-Legal Statement
-~~~~~~~~~~~~~~~
-
-This work represents the view of the author and does not necessarily
-represent the view of IBM.
-
-Linux is a registered trademark of Linus Torvalds.
-
-Other company, product, and service names may be trademarks or service
-marks of others.

Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp.svg

@@ -3880,7 +3880,7 @@
          font-style="normal"
          y="-4418.6582"
          x="3745.7725"
-         xml:space="preserve">rcu_note_context_switch()</text>
+         xml:space="preserve">rcu_node_context_switch()</text>
     </g>
     <g
        transform="translate(1881.1886,54048.57)"

Documentation/RCU/Design/Memory-Ordering/TreeRCU-qs.svg

@@ -753,7 +753,7 @@
          font-style="normal"
          y="-4418.6582"
          x="3745.7725"
-         xml:space="preserve">rcu_note_context_switch()</text>
+         xml:space="preserve">rcu_node_context_switch()</text>
     </g>
     <g
        transform="translate(3131.2648,-585.6713)"

Documentation/RCU/NMI-RCU.rst

@@ -1,124 +0,0 @@
-.. _NMI_rcu_doc:
-
-Using RCU to Protect Dynamic NMI Handlers
-=========================================
-
-
-Although RCU is usually used to protect read-mostly data structures,
-it is possible to use RCU to provide dynamic non-maskable interrupt
-handlers, as well as dynamic irq handlers.  This document describes
-how to do this, drawing loosely from Zwane Mwaikambo's NMI-timer
-work in "arch/x86/oprofile/nmi_timer_int.c" and in
-"arch/x86/kernel/traps.c".
-
-The relevant pieces of code are listed below, each followed by a
-brief explanation::
-
-	static int dummy_nmi_callback(struct pt_regs *regs, int cpu)
-	{
-		return 0;
-	}
-
-The dummy_nmi_callback() function is a "dummy" NMI handler that does
-nothing, but returns zero, thus saying that it did nothing, allowing
-the NMI handler to take the default machine-specific action::
-
-	static nmi_callback_t nmi_callback = dummy_nmi_callback;
-
-This nmi_callback variable is a global function pointer to the current
-NMI handler::
-
-	void do_nmi(struct pt_regs * regs, long error_code)
-	{
-		int cpu;
-
-		nmi_enter();
-
-		cpu = smp_processor_id();
-		++nmi_count(cpu);
-
-		if (!rcu_dereference_sched(nmi_callback)(regs, cpu))
-			default_do_nmi(regs);
-
-		nmi_exit();
-	}
-
-The do_nmi() function processes each NMI.  It first disables preemption
-in the same way that a hardware irq would, then increments the per-CPU
-count of NMIs.  It then invokes the NMI handler stored in the nmi_callback
-function pointer.  If this handler returns zero, do_nmi() invokes the
-default_do_nmi() function to handle a machine-specific NMI.  Finally,
-preemption is restored.
-
-In theory, rcu_dereference_sched() is not needed, since this code runs
-only on i386, which in theory does not need rcu_dereference_sched()
-anyway.  However, in practice it is a good documentation aid, particularly
-for anyone attempting to do something similar on Alpha or on systems
-with aggressive optimizing compilers.
-
-Quick Quiz:
-		Why might the rcu_dereference_sched() be necessary on Alpha, given that the code referenced by the pointer is read-only?
-
-:ref:`Answer to Quick Quiz <answer_quick_quiz_NMI>`
-
-Back to the discussion of NMI and RCU::
-
-	void set_nmi_callback(nmi_callback_t callback)
-	{
-		rcu_assign_pointer(nmi_callback, callback);
-	}
-
-The set_nmi_callback() function registers an NMI handler.  Note that any
-data that is to be used by the callback must be initialized up -before-
-the call to set_nmi_callback().  On architectures that do not order
-writes, the rcu_assign_pointer() ensures that the NMI handler sees the
-initialized values::
-
-	void unset_nmi_callback(void)
-	{
-		rcu_assign_pointer(nmi_callback, dummy_nmi_callback);
-	}
-
-This function unregisters an NMI handler, restoring the original
-dummy_nmi_handler().  However, there may well be an NMI handler
-currently executing on some other CPU.  We therefore cannot free
-up any data structures used by the old NMI handler until execution
-of it completes on all other CPUs.
-
-One way to accomplish this is via synchronize_rcu(), perhaps as
-follows::
-
-	unset_nmi_callback();
-	synchronize_rcu();
-	kfree(my_nmi_data);
-
-This works because (as of v4.20) synchronize_rcu() blocks until all
-CPUs complete any preemption-disabled segments of code that they were
-executing.
-Since NMI handlers disable preemption, synchronize_rcu() is guaranteed
-not to return until all ongoing NMI handlers exit.  It is therefore safe
-to free up the handler's data as soon as synchronize_rcu() returns.
-
-Important note: for this to work, the architecture in question must
-invoke nmi_enter() and nmi_exit() on NMI entry and exit, respectively.
-
-.. _answer_quick_quiz_NMI:
-
-Answer to Quick Quiz:
-	Why might the rcu_dereference_sched() be necessary on Alpha, given that the code referenced by the pointer is read-only?
-
-	The caller to set_nmi_callback() might well have
-	initialized some data that is to be used by the new NMI
-	handler.  In this case, the rcu_dereference_sched() would
-	be needed, because otherwise a CPU that received an NMI
-	just after the new handler was set might see the pointer
-	to the new NMI handler, but the old pre-initialized
-	version of the handler's data.
-
-	This same sad story can happen on other CPUs when using
-	a compiler with aggressive pointer-value speculation
-	optimizations.
-
-	More important, the rcu_dereference_sched() makes it
-	clear to someone reading the code that the pointer is
-	being protected by RCU-sched.

Documentation/RCU/NMI-RCU.txt

@@ -0,0 +1,121 @@
+Using RCU to Protect Dynamic NMI Handlers
+
+
+Although RCU is usually used to protect read-mostly data structures,
+it is possible to use RCU to provide dynamic non-maskable interrupt
+handlers, as well as dynamic irq handlers.  This document describes
+how to do this, drawing loosely from Zwane Mwaikambo's NMI-timer
+work in "arch/x86/oprofile/nmi_timer_int.c" and in
+"arch/x86/kernel/traps.c".
+
+The relevant pieces of code are listed below, each followed by a
+brief explanation.
+
+	static int dummy_nmi_callback(struct pt_regs *regs, int cpu)
+	{
+		return 0;
+	}
+
+The dummy_nmi_callback() function is a "dummy" NMI handler that does
+nothing, but returns zero, thus saying that it did nothing, allowing
+the NMI handler to take the default machine-specific action.
+
+	static nmi_callback_t nmi_callback = dummy_nmi_callback;
+
+This nmi_callback variable is a global function pointer to the current
+NMI handler.
+
+	void do_nmi(struct pt_regs * regs, long error_code)
+	{
+		int cpu;
+
+		nmi_enter();
+
+		cpu = smp_processor_id();
+		++nmi_count(cpu);
+
+		if (!rcu_dereference_sched(nmi_callback)(regs, cpu))
+			default_do_nmi(regs);
+
+		nmi_exit();
+	}
+
+The do_nmi() function processes each NMI.  It first disables preemption
+in the same way that a hardware irq would, then increments the per-CPU
+count of NMIs.  It then invokes the NMI handler stored in the nmi_callback
+function pointer.  If this handler returns zero, do_nmi() invokes the
+default_do_nmi() function to handle a machine-specific NMI.  Finally,
+preemption is restored.
+
+In theory, rcu_dereference_sched() is not needed, since this code runs
+only on i386, which in theory does not need rcu_dereference_sched()
+anyway.  However, in practice it is a good documentation aid, particularly
+for anyone attempting to do something similar on Alpha or on systems
+with aggressive optimizing compilers.
+
+Quick Quiz:  Why might the rcu_dereference_sched() be necessary on Alpha,
+	     given that the code referenced by the pointer is read-only?
+
+
+Back to the discussion of NMI and RCU...
+
+	void set_nmi_callback(nmi_callback_t callback)
+	{
+		rcu_assign_pointer(nmi_callback, callback);
+	}
+
+The set_nmi_callback() function registers an NMI handler.  Note that any
+data that is to be used by the callback must be initialized up -before-
+the call to set_nmi_callback().  On architectures that do not order
+writes, the rcu_assign_pointer() ensures that the NMI handler sees the
+initialized values.
+
+	void unset_nmi_callback(void)
+	{
+		rcu_assign_pointer(nmi_callback, dummy_nmi_callback);
+	}
+
+This function unregisters an NMI handler, restoring the original
+dummy_nmi_handler().  However, there may well be an NMI handler
+currently executing on some other CPU.  We therefore cannot free
+up any data structures used by the old NMI handler until execution
+of it completes on all other CPUs.
+
+One way to accomplish this is via synchronize_rcu(), perhaps as
+follows:
+
+	unset_nmi_callback();
+	synchronize_rcu();
+	kfree(my_nmi_data);
+
+This works because (as of v4.20) synchronize_rcu() blocks until all
+CPUs complete any preemption-disabled segments of code that they were
+executing.
+Since NMI handlers disable preemption, synchronize_rcu() is guaranteed
+not to return until all ongoing NMI handlers exit.  It is therefore safe
+to free up the handler's data as soon as synchronize_rcu() returns.
+
+Important note: for this to work, the architecture in question must
+invoke nmi_enter() and nmi_exit() on NMI entry and exit, respectively.
+
+
+Answer to Quick Quiz
+
+	Why might the rcu_dereference_sched() be necessary on Alpha, given
+	that the code referenced by the pointer is read-only?
+
+	Answer: The caller to set_nmi_callback() might well have
+		initialized some data that is to be used by the new NMI
+		handler.  In this case, the rcu_dereference_sched() would
+		be needed, because otherwise a CPU that received an NMI
+		just after the new handler was set might see the pointer
+		to the new NMI handler, but the old pre-initialized
+		version of the handler's data.
+
+		This same sad story can happen on other CPUs when using
+		a compiler with aggressive pointer-value speculation
+		optimizations.
+
+		More important, the rcu_dereference_sched() makes it
+		clear to someone reading the code that the pointer is
+		being protected by RCU-sched.

Documentation/RCU/arrayRCU.rst

@@ -1,165 +0,0 @@
-.. _array_rcu_doc:
-
-Using RCU to Protect Read-Mostly Arrays
-=======================================
-
-Although RCU is more commonly used to protect linked lists, it can
-also be used to protect arrays.  Three situations are as follows:
-
-1.  :ref:`Hash Tables <hash_tables>`
-
-2.  :ref:`Static Arrays <static_arrays>`
-
-3.  :ref:`Resizable Arrays <resizable_arrays>`
-
-Each of these three situations involves an RCU-protected pointer to an
-array that is separately indexed.  It might be tempting to consider use
-of RCU to instead protect the index into an array, however, this use
-case is **not** supported.  The problem with RCU-protected indexes into
-arrays is that compilers can play way too many optimization games with
-integers, which means that the rules governing handling of these indexes
-are far more trouble than they are worth.  If RCU-protected indexes into
-arrays prove to be particularly valuable (which they have not thus far),
-explicit cooperation from the compiler will be required to permit them
-to be safely used.
-
-That aside, each of the three RCU-protected pointer situations are
-described in the following sections.
-
-.. _hash_tables:
-
-Situation 1: Hash Tables
-------------------------
-
-Hash tables are often implemented as an array, where each array entry
-has a linked-list hash chain.  Each hash chain can be protected by RCU
-as described in the listRCU.txt document.  This approach also applies
-to other array-of-list situations, such as radix trees.
-
-.. _static_arrays:
-
-Situation 2: Static Arrays
---------------------------
-
-Static arrays, where the data (rather than a pointer to the data) is
-located in each array element, and where the array is never resized,
-have not been used with RCU.  Rik van Riel recommends using seqlock in
-this situation, which would also have minimal read-side overhead as long
-as updates are rare.
-
-Quick Quiz:
-		Why is it so important that updates be rare when using seqlock?
-
-:ref:`Answer to Quick Quiz <answer_quick_quiz_seqlock>`
-
-.. _resizable_arrays:
-
-Situation 3: Resizable Arrays
-------------------------------
-
-Use of RCU for resizable arrays is demonstrated by the grow_ary()
-function formerly used by the System V IPC code.  The array is used
-to map from semaphore, message-queue, and shared-memory IDs to the data
-structure that represents the corresponding IPC construct.  The grow_ary()
-function does not acquire any locks; instead its caller must hold the
-ids->sem semaphore.
-
-The grow_ary() function, shown below, does some limit checks, allocates a
-new ipc_id_ary, copies the old to the new portion of the new, initializes
-the remainder of the new, updates the ids->entries pointer to point to
-the new array, and invokes ipc_rcu_putref() to free up the old array.
-Note that rcu_assign_pointer() is used to update the ids->entries pointer,
-which includes any memory barriers required on whatever architecture
-you are running on::
-
-	static int grow_ary(struct ipc_ids* ids, int newsize)
-	{
-		struct ipc_id_ary* new;
-		struct ipc_id_ary* old;
-		int i;
-		int size = ids->entries->size;
-
-		if(newsize > IPCMNI)
-			newsize = IPCMNI;
-		if(newsize <= size)
-			return newsize;
-
-		new = ipc_rcu_alloc(sizeof(struct kern_ipc_perm *)*newsize +
-				    sizeof(struct ipc_id_ary));
-		if(new == NULL)
-			return size;
-		new->size = newsize;
-		memcpy(new->p, ids->entries->p,
-		       sizeof(struct kern_ipc_perm *)*size +
-		       sizeof(struct ipc_id_ary));
-		for(i=size;i<newsize;i++) {
-			new->p[i] = NULL;
-		}
-		old = ids->entries;
-
-		/*
-		 * Use rcu_assign_pointer() to make sure the memcpyed
-		 * contents of the new array are visible before the new
-		 * array becomes visible.
-		 */
-		rcu_assign_pointer(ids->entries, new);
-
-		ipc_rcu_putref(old);
-		return newsize;
-	}
-
-The ipc_rcu_putref() function decrements the array's reference count
-and then, if the reference count has dropped to zero, uses call_rcu()
-to free the array after a grace period has elapsed.
-
-The array is traversed by the ipc_lock() function.  This function
-indexes into the array under the protection of rcu_read_lock(),
-using rcu_dereference() to pick up the pointer to the array so
-that it may later safely be dereferenced -- memory barriers are
-required on the Alpha CPU.  Since the size of the array is stored
-with the array itself, there can be no array-size mismatches, so
-a simple check suffices.  The pointer to the structure corresponding
-to the desired IPC object is placed in "out", with NULL indicating
-a non-existent entry.  After acquiring "out->lock", the "out->deleted"
-flag indicates whether the IPC object is in the process of being
-deleted, and, if not, the pointer is returned::
-
-	struct kern_ipc_perm* ipc_lock(struct ipc_ids* ids, int id)
-	{
-		struct kern_ipc_perm* out;
-		int lid = id % SEQ_MULTIPLIER;
-		struct ipc_id_ary* entries;
-
-		rcu_read_lock();
-		entries = rcu_dereference(ids->entries);
-		if(lid >= entries->size) {
-			rcu_read_unlock();
-			return NULL;
-		}
-		out = entries->p[lid];
-		if(out == NULL) {
-			rcu_read_unlock();
-			return NULL;
-		}
-		spin_lock(&out->lock);
-
-		/* ipc_rmid() may have already freed the ID while ipc_lock
-		 * was spinning: here verify that the structure is still valid
-		 */
-		if (out->deleted) {
-			spin_unlock(&out->lock);
-			rcu_read_unlock();
-			return NULL;
-		}
-		return out;
-	}
-
-.. _answer_quick_quiz_seqlock:
-
-Answer to Quick Quiz:
-	Why is it so important that updates be rare when using seqlock?
-
-	The reason that it is important that updates be rare when
-	using seqlock is that frequent updates can livelock readers.
-	One way to avoid this problem is to assign a seqlock for
-	each array entry rather than to the entire array.

Documentation/RCU/arrayRCU.txt

@@ -0,0 +1,153 @@
+Using RCU to Protect Read-Mostly Arrays
+
+
+Although RCU is more commonly used to protect linked lists, it can
+also be used to protect arrays.  Three situations are as follows:
+
+1.  Hash Tables
+
+2.  Static Arrays
+
+3.  Resizeable Arrays
+
+Each of these three situations involves an RCU-protected pointer to an
+array that is separately indexed.  It might be tempting to consider use
+of RCU to instead protect the index into an array, however, this use
+case is -not- supported.  The problem with RCU-protected indexes into
+arrays is that compilers can play way too many optimization games with
+integers, which means that the rules governing handling of these indexes
+are far more trouble than they are worth.  If RCU-protected indexes into
+arrays prove to be particularly valuable (which they have not thus far),
+explicit cooperation from the compiler will be required to permit them
+to be safely used.
+
+That aside, each of the three RCU-protected pointer situations are
+described in the following sections.
+
+
+Situation 1: Hash Tables
+
+Hash tables are often implemented as an array, where each array entry
+has a linked-list hash chain.  Each hash chain can be protected by RCU
+as described in the listRCU.txt document.  This approach also applies
+to other array-of-list situations, such as radix trees.
+
+
+Situation 2: Static Arrays
+
+Static arrays, where the data (rather than a pointer to the data) is
+located in each array element, and where the array is never resized,
+have not been used with RCU.  Rik van Riel recommends using seqlock in
+this situation, which would also have minimal read-side overhead as long
+as updates are rare.
+
+Quick Quiz:  Why is it so important that updates be rare when
+	     using seqlock?
+
+
+Situation 3: Resizeable Arrays
+
+Use of RCU for resizeable arrays is demonstrated by the grow_ary()
+function formerly used by the System V IPC code.  The array is used
+to map from semaphore, message-queue, and shared-memory IDs to the data
+structure that represents the corresponding IPC construct.  The grow_ary()
+function does not acquire any locks; instead its caller must hold the
+ids->sem semaphore.
+
+The grow_ary() function, shown below, does some limit checks, allocates a
+new ipc_id_ary, copies the old to the new portion of the new, initializes
+the remainder of the new, updates the ids->entries pointer to point to
+the new array, and invokes ipc_rcu_putref() to free up the old array.
+Note that rcu_assign_pointer() is used to update the ids->entries pointer,
+which includes any memory barriers required on whatever architecture
+you are running on.
+
+	static int grow_ary(struct ipc_ids* ids, int newsize)
+	{
+		struct ipc_id_ary* new;
+		struct ipc_id_ary* old;
+		int i;
+		int size = ids->entries->size;
+
+		if(newsize > IPCMNI)
+			newsize = IPCMNI;
+		if(newsize <= size)
+			return newsize;
+
+		new = ipc_rcu_alloc(sizeof(struct kern_ipc_perm *)*newsize +
+				    sizeof(struct ipc_id_ary));
+		if(new == NULL)
+			return size;
+		new->size = newsize;
+		memcpy(new->p, ids->entries->p,
+		       sizeof(struct kern_ipc_perm *)*size +
+		       sizeof(struct ipc_id_ary));
+		for(i=size;i<newsize;i++) {
+			new->p[i] = NULL;
+		}
+		old = ids->entries;
+
+		/*
+		 * Use rcu_assign_pointer() to make sure the memcpyed
+		 * contents of the new array are visible before the new
+		 * array becomes visible.
+		 */
+		rcu_assign_pointer(ids->entries, new);
+
+		ipc_rcu_putref(old);
+		return newsize;
+	}
+
+The ipc_rcu_putref() function decrements the array's reference count
+and then, if the reference count has dropped to zero, uses call_rcu()
+to free the array after a grace period has elapsed.
+
+The array is traversed by the ipc_lock() function.  This function
+indexes into the array under the protection of rcu_read_lock(),
+using rcu_dereference() to pick up the pointer to the array so
+that it may later safely be dereferenced -- memory barriers are
+required on the Alpha CPU.  Since the size of the array is stored
+with the array itself, there can be no array-size mismatches, so
+a simple check suffices.  The pointer to the structure corresponding
+to the desired IPC object is placed in "out", with NULL indicating
+a non-existent entry.  After acquiring "out->lock", the "out->deleted"
+flag indicates whether the IPC object is in the process of being
+deleted, and, if not, the pointer is returned.
+
+	struct kern_ipc_perm* ipc_lock(struct ipc_ids* ids, int id)
+	{
+		struct kern_ipc_perm* out;
+		int lid = id % SEQ_MULTIPLIER;
+		struct ipc_id_ary* entries;
+
+		rcu_read_lock();
+		entries = rcu_dereference(ids->entries);
+		if(lid >= entries->size) {
+			rcu_read_unlock();
+			return NULL;
+		}
+		out = entries->p[lid];
+		if(out == NULL) {
+			rcu_read_unlock();
+			return NULL;
+		}
+		spin_lock(&out->lock);
+
+		/* ipc_rmid() may have already freed the ID while ipc_lock
+		 * was spinning: here verify that the structure is still valid
+		 */
+		if (out->deleted) {
+			spin_unlock(&out->lock);
+			rcu_read_unlock();
+			return NULL;
+		}
+		return out;
+	}
+
+
+Answer to Quick Quiz:
+
+	The reason that it is important that updates be rare when
+	using seqlock is that frequent updates can livelock readers.
+	One way to avoid this problem is to assign a seqlock for
+	each array entry rather than to the entire array.

Documentation/RCU/index.rst

@@ -5,22 +5,12 @@ RCU concepts
 ============
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 1
 
-   arrayRCU
-   rcubarrier
-   rcu_dereference
-   whatisRCU
    rcu
    listRCU
-   NMI-RCU
    UP
 
-   Design/Memory-Ordering/Tree-RCU-Memory-Ordering
-   Design/Expedited-Grace-Periods/Expedited-Grace-Periods
-   Design/Requirements/Requirements
-   Design/Data-Structures/Data-Structures
-
 .. only:: subproject and html
 
    Indices

Documentation/RCU/lockdep-splat.txt

@@ -99,7 +99,7 @@ With this change, the rcu_dereference() is always within an RCU
 read-side critical section, which again would have suppressed the
 above lockdep-RCU splat.
 
-But in this particular case, we don't actually dereference the pointer
+But in this particular case, we don't actually deference the pointer
 returned from rcu_dereference().  Instead, that pointer is just compared
 to the cic pointer, which means that the rcu_dereference() can be replaced
 by rcu_access_pointer() as follows:

Documentation/RCU/lockdep.txt

@@ -96,17 +96,7 @@ other flavors of rcu_dereference().  On the other hand, it is illegal
 to use rcu_dereference_protected() if either the RCU-protected pointer
 or the RCU-protected data that it points to can change concurrently.
 
-Like rcu_dereference(), when lockdep is enabled, RCU list and hlist
-traversal primitives check for being called from within an RCU read-side
-critical section.  However, a lockdep expression can be passed to them
-as a additional optional argument.  With this lockdep expression, these
-traversal primitives will complain only if the lockdep expression is
-false and they are called from outside any RCU read-side critical section.
-
-For example, the workqueue for_each_pwq() macro is intended to be used
-either within an RCU read-side critical section or with wq->mutex held.
-It is thus implemented as follows:
-
-	#define for_each_pwq(pwq, wq)
-		list_for_each_entry_rcu((pwq), &(wq)->pwqs, pwqs_node,
-					lock_is_held(&(wq->mutex).dep_map))
+There are currently only "universal" versions of the rcu_assign_pointer()
+and RCU list-/tree-traversal primitives, which do not (yet) check for
+being in an RCU read-side critical section.  In the future, separate
+versions of these primitives might be created.

Documentation/RCU/rcu_dereference.rst

@@ -1,463 +0,0 @@
-.. _rcu_dereference_doc:
-
-PROPER CARE AND FEEDING OF RETURN VALUES FROM rcu_dereference()
-===============================================================
-
-Most of the time, you can use values from rcu_dereference() or one of
-the similar primitives without worries.  Dereferencing (prefix "*"),
-field selection ("->"), assignment ("="), address-of ("&"), addition and
-subtraction of constants, and casts all work quite naturally and safely.
-
-It is nevertheless possible to get into trouble with other operations.
-Follow these rules to keep your RCU code working properly:
-
--	You must use one of the rcu_dereference() family of primitives
-	to load an RCU-protected pointer, otherwise CONFIG_PROVE_RCU
-	will complain.  Worse yet, your code can see random memory-corruption
-	bugs due to games that compilers and DEC Alpha can play.
-	Without one of the rcu_dereference() primitives, compilers
-	can reload the value, and won't your code have fun with two
-	different values for a single pointer!  Without rcu_dereference(),
-	DEC Alpha can load a pointer, dereference that pointer, and
-	return data preceding initialization that preceded the store of
-	the pointer.
-
-	In addition, the volatile cast in rcu_dereference() prevents the
-	compiler from deducing the resulting pointer value.  Please see
-	the section entitled "EXAMPLE WHERE THE COMPILER KNOWS TOO MUCH"
-	for an example where the compiler can in fact deduce the exact
-	value of the pointer, and thus cause misordering.
-
--	You are only permitted to use rcu_dereference on pointer values.
-	The compiler simply knows too much about integral values to
-	trust it to carry dependencies through integer operations.
-	There are a very few exceptions, namely that you can temporarily
-	cast the pointer to uintptr_t in order to:
-
-	-	Set bits and clear bits down in the must-be-zero low-order
-		bits of that pointer.  This clearly means that the pointer
-		must have alignment constraints, for example, this does
-		-not- work in general for char* pointers.
-
-	-	XOR bits to translate pointers, as is done in some
-		classic buddy-allocator algorithms.
-
-	It is important to cast the value back to pointer before
-	doing much of anything else with it.
-
--	Avoid cancellation when using the "+" and "-" infix arithmetic
-	operators.  For example, for a given variable "x", avoid
-	"(x-(uintptr_t)x)" for char* pointers.	The compiler is within its
-	rights to substitute zero for this sort of expression, so that
-	subsequent accesses no longer depend on the rcu_dereference(),
-	again possibly resulting in bugs due to misordering.
-
-	Of course, if "p" is a pointer from rcu_dereference(), and "a"
-	and "b" are integers that happen to be equal, the expression
-	"p+a-b" is safe because its value still necessarily depends on
-	the rcu_dereference(), thus maintaining proper ordering.
-
--	If you are using RCU to protect JITed functions, so that the
-	"()" function-invocation operator is applied to a value obtained
-	(directly or indirectly) from rcu_dereference(), you may need to
-	interact directly with the hardware to flush instruction caches.
-	This issue arises on some systems when a newly JITed function is
-	using the same memory that was used by an earlier JITed function.
-
--	Do not use the results from relational operators ("==", "!=",
-	">", ">=", "<", or "<=") when dereferencing.  For example,
-	the following (quite strange) code is buggy::
-
-		int *p;
-		int *q;
-
-		...
-
-		p = rcu_dereference(gp)
-		q = &global_q;
-		q += p > &oom_p;
-		r1 = *q;  /* BUGGY!!! */
-
-	As before, the reason this is buggy is that relational operators
-	are often compiled using branches.  And as before, although
-	weak-memory machines such as ARM or PowerPC do order stores
-	after such branches, but can speculate loads, which can again
-	result in misordering bugs.
-
--	Be very careful about comparing pointers obtained from
-	rcu_dereference() against non-NULL values.  As Linus Torvalds
-	explained, if the two pointers are equal, the compiler could
-	substitute the pointer you are comparing against for the pointer
-	obtained from rcu_dereference().  For example::
-
-		p = rcu_dereference(gp);
-		if (p == &default_struct)
-			do_default(p->a);
-
-	Because the compiler now knows that the value of "p" is exactly
-	the address of the variable "default_struct", it is free to
-	transform this code into the following::
-
-		p = rcu_dereference(gp);
-		if (p == &default_struct)
-			do_default(default_struct.a);
-
-	On ARM and Power hardware, the load from "default_struct.a"
-	can now be speculated, such that it might happen before the
-	rcu_dereference().  This could result in bugs due to misordering.
-
-	However, comparisons are OK in the following cases:
-
-	-	The comparison was against the NULL pointer.  If the
-		compiler knows that the pointer is NULL, you had better
-		not be dereferencing it anyway.  If the comparison is
-		non-equal, the compiler is none the wiser.  Therefore,
-		it is safe to compare pointers from rcu_dereference()
-		against NULL pointers.
-
-	-	The pointer is never dereferenced after being compared.
-		Since there are no subsequent dereferences, the compiler
-		cannot use anything it learned from the comparison
-		to reorder the non-existent subsequent dereferences.
-		This sort of comparison occurs frequently when scanning
-		RCU-protected circular linked lists.
-
-		Note that if checks for being within an RCU read-side
-		critical section are not required and the pointer is never
-		dereferenced, rcu_access_pointer() should be used in place
-		of rcu_dereference().
-
-	-	The comparison is against a pointer that references memory
-		that was initialized "a long time ago."  The reason
-		this is safe is that even if misordering occurs, the
-		misordering will not affect the accesses that follow
-		the comparison.  So exactly how long ago is "a long
-		time ago"?  Here are some possibilities:
-
-		-	Compile time.
-
-		-	Boot time.
-
-		-	Module-init time for module code.
-
-		-	Prior to kthread creation for kthread code.
-
-		-	During some prior acquisition of the lock that
-			we now hold.
-
-		-	Before mod_timer() time for a timer handler.
-
-		There are many other possibilities involving the Linux
-		kernel's wide array of primitives that cause code to
-		be invoked at a later time.
-
-	-	The pointer being compared against also came from
-		rcu_dereference().  In this case, both pointers depend
-		on one rcu_dereference() or another, so you get proper
-		ordering either way.
-
-		That said, this situation can make certain RCU usage
-		bugs more likely to happen.  Which can be a good thing,
-		at least if they happen during testing.  An example
-		of such an RCU usage bug is shown in the section titled
-		"EXAMPLE OF AMPLIFIED RCU-USAGE BUG".
-
-	-	All of the accesses following the comparison are stores,
-		so that a control dependency preserves the needed ordering.
-		That said, it is easy to get control dependencies wrong.
-		Please see the "CONTROL DEPENDENCIES" section of
-		Documentation/memory-barriers.txt for more details.
-
-	-	The pointers are not equal -and- the compiler does
-		not have enough information to deduce the value of the
-		pointer.  Note that the volatile cast in rcu_dereference()
-		will normally prevent the compiler from knowing too much.
-
-		However, please note that if the compiler knows that the
-		pointer takes on only one of two values, a not-equal
-		comparison will provide exactly the information that the
-		compiler needs to deduce the value of the pointer.
-
--	Disable any value-speculation optimizations that your compiler
-	might provide, especially if you are making use of feedback-based
-	optimizations that take data collected from prior runs.  Such
-	value-speculation optimizations reorder operations by design.
-
-	There is one exception to this rule:  Value-speculation
-	optimizations that leverage the branch-prediction hardware are
-	safe on strongly ordered systems (such as x86), but not on weakly
-	ordered systems (such as ARM or Power).  Choose your compiler
-	command-line options wisely!
-
-
-EXAMPLE OF AMPLIFIED RCU-USAGE BUG
-----------------------------------
-
-Because updaters can run concurrently with RCU readers, RCU readers can
-see stale and/or inconsistent values.  If RCU readers need fresh or
-consistent values, which they sometimes do, they need to take proper
-precautions.  To see this, consider the following code fragment::
-
-	struct foo {
-		int a;
-		int b;
-		int c;
-	};
-	struct foo *gp1;
-	struct foo *gp2;
-
-	void updater(void)
-	{
-		struct foo *p;
-
-		p = kmalloc(...);
-		if (p == NULL)
-			deal_with_it();
-		p->a = 42;  /* Each field in its own cache line. */
-		p->b = 43;
-		p->c = 44;
-		rcu_assign_pointer(gp1, p);
-		p->b = 143;
-		p->c = 144;
-		rcu_assign_pointer(gp2, p);
-	}
-
-	void reader(void)
-	{
-		struct foo *p;
-		struct foo *q;
-		int r1, r2;
-
-		p = rcu_dereference(gp2);
-		if (p == NULL)
-			return;
-		r1 = p->b;  /* Guaranteed to get 143. */
-		q = rcu_dereference(gp1);  /* Guaranteed non-NULL. */
-		if (p == q) {
-			/* The compiler decides that q->c is same as p->c. */
-			r2 = p->c; /* Could get 44 on weakly order system. */
-		}
-		do_something_with(r1, r2);
-	}
-
-You might be surprised that the outcome (r1 == 143 && r2 == 44) is possible,
-but you should not be.  After all, the updater might have been invoked
-a second time between the time reader() loaded into "r1" and the time
-that it loaded into "r2".  The fact that this same result can occur due
-to some reordering from the compiler and CPUs is beside the point.
-
-But suppose that the reader needs a consistent view?
-
-Then one approach is to use locking, for example, as follows::
-
-	struct foo {
-		int a;
-		int b;
-		int c;
-		spinlock_t lock;
-	};
-	struct foo *gp1;
-	struct foo *gp2;
-
-	void updater(void)
-	{
-		struct foo *p;
-
-		p = kmalloc(...);
-		if (p == NULL)
-			deal_with_it();
-		spin_lock(&p->lock);
-		p->a = 42;  /* Each field in its own cache line. */
-		p->b = 43;
-		p->c = 44;
-		spin_unlock(&p->lock);
-		rcu_assign_pointer(gp1, p);
-		spin_lock(&p->lock);
-		p->b = 143;
-		p->c = 144;
-		spin_unlock(&p->lock);
-		rcu_assign_pointer(gp2, p);
-	}
-
-	void reader(void)
-	{
-		struct foo *p;
-		struct foo *q;
-		int r1, r2;
-
-		p = rcu_dereference(gp2);
-		if (p == NULL)
-			return;
-		spin_lock(&p->lock);
-		r1 = p->b;  /* Guaranteed to get 143. */
-		q = rcu_dereference(gp1);  /* Guaranteed non-NULL. */
-		if (p == q) {
-			/* The compiler decides that q->c is same as p->c. */
-			r2 = p->c; /* Locking guarantees r2 == 144. */
-		}
-		spin_unlock(&p->lock);
-		do_something_with(r1, r2);
-	}
-
-As always, use the right tool for the job!
-
-
-EXAMPLE WHERE THE COMPILER KNOWS TOO MUCH
------------------------------------------
-
-If a pointer obtained from rcu_dereference() compares not-equal to some
-other pointer, the compiler normally has no clue what the value of the
-first pointer might be.  This lack of knowledge prevents the compiler
-from carrying out optimizations that otherwise might destroy the ordering
-guarantees that RCU depends on.  And the volatile cast in rcu_dereference()
-should prevent the compiler from guessing the value.
-
-But without rcu_dereference(), the compiler knows more than you might
-expect.  Consider the following code fragment::
-
-	struct foo {
-		int a;
-		int b;
-	};
-	static struct foo variable1;
-	static struct foo variable2;
-	static struct foo *gp = &variable1;
-
-	void updater(void)
-	{
-		initialize_foo(&variable2);
-		rcu_assign_pointer(gp, &variable2);
-		/*
-		 * The above is the only store to gp in this translation unit,
-		 * and the address of gp is not exported in any way.
-		 */
-	}
-
-	int reader(void)
-	{
-		struct foo *p;
-
-		p = gp;
-		barrier();
-		if (p == &variable1)
-			return p->a; /* Must be variable1.a. */
-		else
-			return p->b; /* Must be variable2.b. */
-	}
-
-Because the compiler can see all stores to "gp", it knows that the only
-possible values of "gp" are "variable1" on the one hand and "variable2"
-on the other.  The comparison in reader() therefore tells the compiler
-the exact value of "p" even in the not-equals case.  This allows the
-compiler to make the return values independent of the load from "gp",
-in turn destroying the ordering between this load and the loads of the
-return values.  This can result in "p->b" returning pre-initialization
-garbage values.
-
-In short, rcu_dereference() is -not- optional when you are going to
-dereference the resulting pointer.
-
-
-WHICH MEMBER OF THE rcu_dereference() FAMILY SHOULD YOU USE?
-------------------------------------------------------------
-
-First, please avoid using rcu_dereference_raw() and also please avoid
-using rcu_dereference_check() and rcu_dereference_protected() with a
-second argument with a constant value of 1 (or true, for that matter).
-With that caution out of the way, here is some guidance for which
-member of the rcu_dereference() to use in various situations:
-
-1.	If the access needs to be within an RCU read-side critical
-	section, use rcu_dereference().  With the new consolidated
-	RCU flavors, an RCU read-side critical section is entered
-	using rcu_read_lock(), anything that disables bottom halves,
-	anything that disables interrupts, or anything that disables
-	preemption.
-
-2.	If the access might be within an RCU read-side critical section
-	on the one hand, or protected by (say) my_lock on the other,
-	use rcu_dereference_check(), for example::
-
-		p1 = rcu_dereference_check(p->rcu_protected_pointer,
-					   lockdep_is_held(&my_lock));
-
-
-3.	If the access might be within an RCU read-side critical section
-	on the one hand, or protected by either my_lock or your_lock on
-	the other, again use rcu_dereference_check(), for example::
-
-		p1 = rcu_dereference_check(p->rcu_protected_pointer,
-					   lockdep_is_held(&my_lock) ||
-					   lockdep_is_held(&your_lock));
-
-4.	If the access is on the update side, so that it is always protected
-	by my_lock, use rcu_dereference_protected()::
-
-		p1 = rcu_dereference_protected(p->rcu_protected_pointer,
-					       lockdep_is_held(&my_lock));
-
-	This can be extended to handle multiple locks as in #3 above,
-	and both can be extended to check other conditions as well.
-
-5.	If the protection is supplied by the caller, and is thus unknown
-	to this code, that is the rare case when rcu_dereference_raw()
-	is appropriate.  In addition, rcu_dereference_raw() might be
-	appropriate when the lockdep expression would be excessively
-	complex, except that a better approach in that case might be to
-	take a long hard look at your synchronization design.  Still,
-	there are data-locking cases where any one of a very large number
-	of locks or reference counters suffices to protect the pointer,
-	so rcu_dereference_raw() does have its place.
-
-	However, its place is probably quite a bit smaller than one
-	might expect given the number of uses in the current kernel.
-	Ditto for its synonym, rcu_dereference_check( ... , 1), and
-	its close relative, rcu_dereference_protected(... , 1).
-
-
-SPARSE CHECKING OF RCU-PROTECTED POINTERS
------------------------------------------
-
-The sparse static-analysis tool checks for direct access to RCU-protected
-pointers, which can result in "interesting" bugs due to compiler
-optimizations involving invented loads and perhaps also load tearing.
-For example, suppose someone mistakenly does something like this::
-
-	p = q->rcu_protected_pointer;
-	do_something_with(p->a);
-	do_something_else_with(p->b);
-
-If register pressure is high, the compiler might optimize "p" out
-of existence, transforming the code to something like this::
-
-	do_something_with(q->rcu_protected_pointer->a);
-	do_something_else_with(q->rcu_protected_pointer->b);
-
-This could fatally disappoint your code if q->rcu_protected_pointer
-changed in the meantime.  Nor is this a theoretical problem:  Exactly
-this sort of bug cost Paul E. McKenney (and several of his innocent
-colleagues) a three-day weekend back in the early 1990s.
-
-Load tearing could of course result in dereferencing a mashup of a pair
-of pointers, which also might fatally disappoint your code.
-
-These problems could have been avoided simply by making the code instead
-read as follows::
-
-	p = rcu_dereference(q->rcu_protected_pointer);
-	do_something_with(p->a);
-	do_something_else_with(p->b);
-
-Unfortunately, these sorts of bugs can be extremely hard to spot during
-review.  This is where the sparse tool comes into play, along with the
-"__rcu" marker.  If you mark a pointer declaration, whether in a structure
-or as a formal parameter, with "__rcu", which tells sparse to complain if
-this pointer is accessed directly.  It will also cause sparse to complain
-if a pointer not marked with "__rcu" is accessed using rcu_dereference()
-and friends.  For example, ->rcu_protected_pointer might be declared as
-follows::
-
-	struct foo __rcu *rcu_protected_pointer;
-
-Use of "__rcu" is opt-in.  If you choose not to use it, then you should
-ignore the sparse warnings.

Documentation/RCU/rcu_dereference.txt

@@ -0,0 +1,456 @@
+PROPER CARE AND FEEDING OF RETURN VALUES FROM rcu_dereference()
+
+Most of the time, you can use values from rcu_dereference() or one of
+the similar primitives without worries.  Dereferencing (prefix "*"),
+field selection ("->"), assignment ("="), address-of ("&"), addition and
+subtraction of constants, and casts all work quite naturally and safely.
+
+It is nevertheless possible to get into trouble with other operations.
+Follow these rules to keep your RCU code working properly:
+
+o	You must use one of the rcu_dereference() family of primitives
+	to load an RCU-protected pointer, otherwise CONFIG_PROVE_RCU
+	will complain.  Worse yet, your code can see random memory-corruption
+	bugs due to games that compilers and DEC Alpha can play.
+	Without one of the rcu_dereference() primitives, compilers
+	can reload the value, and won't your code have fun with two
+	different values for a single pointer!  Without rcu_dereference(),
+	DEC Alpha can load a pointer, dereference that pointer, and
+	return data preceding initialization that preceded the store of
+	the pointer.
+
+	In addition, the volatile cast in rcu_dereference() prevents the
+	compiler from deducing the resulting pointer value.  Please see
+	the section entitled "EXAMPLE WHERE THE COMPILER KNOWS TOO MUCH"
+	for an example where the compiler can in fact deduce the exact
+	value of the pointer, and thus cause misordering.
+
+o	You are only permitted to use rcu_dereference on pointer values.
+	The compiler simply knows too much about integral values to
+	trust it to carry dependencies through integer operations.
+	There are a very few exceptions, namely that you can temporarily
+	cast the pointer to uintptr_t in order to:
+
+	o	Set bits and clear bits down in the must-be-zero low-order
+		bits of that pointer.  This clearly means that the pointer
+		must have alignment constraints, for example, this does
+		-not- work in general for char* pointers.
+
+	o	XOR bits to translate pointers, as is done in some
+		classic buddy-allocator algorithms.
+
+	It is important to cast the value back to pointer before
+	doing much of anything else with it.
+
+o	Avoid cancellation when using the "+" and "-" infix arithmetic
+	operators.  For example, for a given variable "x", avoid
+	"(x-(uintptr_t)x)" for char* pointers.	The compiler is within its
+	rights to substitute zero for this sort of expression, so that
+	subsequent accesses no longer depend on the rcu_dereference(),
+	again possibly resulting in bugs due to misordering.
+
+	Of course, if "p" is a pointer from rcu_dereference(), and "a"
+	and "b" are integers that happen to be equal, the expression
+	"p+a-b" is safe because its value still necessarily depends on
+	the rcu_dereference(), thus maintaining proper ordering.
+
+o	If you are using RCU to protect JITed functions, so that the
+	"()" function-invocation operator is applied to a value obtained
+	(directly or indirectly) from rcu_dereference(), you may need to
+	interact directly with the hardware to flush instruction caches.
+	This issue arises on some systems when a newly JITed function is
+	using the same memory that was used by an earlier JITed function.
+
+o	Do not use the results from relational operators ("==", "!=",
+	">", ">=", "<", or "<=") when dereferencing.  For example,
+	the following (quite strange) code is buggy:
+
+		int *p;
+		int *q;
+
+		...
+
+		p = rcu_dereference(gp)
+		q = &global_q;
+		q += p > &oom_p;
+		r1 = *q;  /* BUGGY!!! */
+
+	As before, the reason this is buggy is that relational operators
+	are often compiled using branches.  And as before, although
+	weak-memory machines such as ARM or PowerPC do order stores
+	after such branches, but can speculate loads, which can again
+	result in misordering bugs.
+
+o	Be very careful about comparing pointers obtained from
+	rcu_dereference() against non-NULL values.  As Linus Torvalds
+	explained, if the two pointers are equal, the compiler could
+	substitute the pointer you are comparing against for the pointer
+	obtained from rcu_dereference().  For example:
+
+		p = rcu_dereference(gp);
+		if (p == &default_struct)
+			do_default(p->a);
+
+	Because the compiler now knows that the value of "p" is exactly
+	the address of the variable "default_struct", it is free to
+	transform this code into the following:
+
+		p = rcu_dereference(gp);
+		if (p == &default_struct)
+			do_default(default_struct.a);
+
+	On ARM and Power hardware, the load from "default_struct.a"
+	can now be speculated, such that it might happen before the
+	rcu_dereference().  This could result in bugs due to misordering.
+
+	However, comparisons are OK in the following cases:
+
+	o	The comparison was against the NULL pointer.  If the
+		compiler knows that the pointer is NULL, you had better
+		not be dereferencing it anyway.  If the comparison is
+		non-equal, the compiler is none the wiser.  Therefore,
+		it is safe to compare pointers from rcu_dereference()
+		against NULL pointers.
+
+	o	The pointer is never dereferenced after being compared.
+		Since there are no subsequent dereferences, the compiler
+		cannot use anything it learned from the comparison
+		to reorder the non-existent subsequent dereferences.
+		This sort of comparison occurs frequently when scanning
+		RCU-protected circular linked lists.
+
+		Note that if checks for being within an RCU read-side
+		critical section are not required and the pointer is never
+		dereferenced, rcu_access_pointer() should be used in place
+		of rcu_dereference().
+
+	o	The comparison is against a pointer that references memory
+		that was initialized "a long time ago."  The reason
+		this is safe is that even if misordering occurs, the
+		misordering will not affect the accesses that follow
+		the comparison.  So exactly how long ago is "a long
+		time ago"?  Here are some possibilities:
+
+		o	Compile time.
+
+		o	Boot time.
+
+		o	Module-init time for module code.
+
+		o	Prior to kthread creation for kthread code.
+
+		o	During some prior acquisition of the lock that
+			we now hold.
+
+		o	Before mod_timer() time for a timer handler.
+
+		There are many other possibilities involving the Linux
+		kernel's wide array of primitives that cause code to
+		be invoked at a later time.
+
+	o	The pointer being compared against also came from
+		rcu_dereference().  In this case, both pointers depend
+		on one rcu_dereference() or another, so you get proper
+		ordering either way.
+
+		That said, this situation can make certain RCU usage
+		bugs more likely to happen.  Which can be a good thing,
+		at least if they happen during testing.  An example
+		of such an RCU usage bug is shown in the section titled
+		"EXAMPLE OF AMPLIFIED RCU-USAGE BUG".
+
+	o	All of the accesses following the comparison are stores,
+		so that a control dependency preserves the needed ordering.
+		That said, it is easy to get control dependencies wrong.
+		Please see the "CONTROL DEPENDENCIES" section of
+		Documentation/memory-barriers.txt for more details.
+
+	o	The pointers are not equal -and- the compiler does
+		not have enough information to deduce the value of the
+		pointer.  Note that the volatile cast in rcu_dereference()
+		will normally prevent the compiler from knowing too much.
+
+		However, please note that if the compiler knows that the
+		pointer takes on only one of two values, a not-equal
+		comparison will provide exactly the information that the
+		compiler needs to deduce the value of the pointer.
+
+o	Disable any value-speculation optimizations that your compiler
+	might provide, especially if you are making use of feedback-based
+	optimizations that take data collected from prior runs.  Such
+	value-speculation optimizations reorder operations by design.
+
+	There is one exception to this rule:  Value-speculation
+	optimizations that leverage the branch-prediction hardware are
+	safe on strongly ordered systems (such as x86), but not on weakly
+	ordered systems (such as ARM or Power).  Choose your compiler
+	command-line options wisely!
+
+
+EXAMPLE OF AMPLIFIED RCU-USAGE BUG
+
+Because updaters can run concurrently with RCU readers, RCU readers can
+see stale and/or inconsistent values.  If RCU readers need fresh or
+consistent values, which they sometimes do, they need to take proper
+precautions.  To see this, consider the following code fragment:
+
+	struct foo {
+		int a;
+		int b;
+		int c;
+	};
+	struct foo *gp1;
+	struct foo *gp2;
+
+	void updater(void)
+	{
+		struct foo *p;
+
+		p = kmalloc(...);
+		if (p == NULL)
+			deal_with_it();
+		p->a = 42;  /* Each field in its own cache line. */
+		p->b = 43;
+		p->c = 44;
+		rcu_assign_pointer(gp1, p);
+		p->b = 143;
+		p->c = 144;
+		rcu_assign_pointer(gp2, p);
+	}
+
+	void reader(void)
+	{
+		struct foo *p;
+		struct foo *q;
+		int r1, r2;
+
+		p = rcu_dereference(gp2);
+		if (p == NULL)
+			return;
+		r1 = p->b;  /* Guaranteed to get 143. */
+		q = rcu_dereference(gp1);  /* Guaranteed non-NULL. */
+		if (p == q) {
+			/* The compiler decides that q->c is same as p->c. */
+			r2 = p->c; /* Could get 44 on weakly order system. */
+		}
+		do_something_with(r1, r2);
+	}
+
+You might be surprised that the outcome (r1 == 143 && r2 == 44) is possible,
+but you should not be.  After all, the updater might have been invoked
+a second time between the time reader() loaded into "r1" and the time
+that it loaded into "r2".  The fact that this same result can occur due
+to some reordering from the compiler and CPUs is beside the point.
+
+But suppose that the reader needs a consistent view?
+
+Then one approach is to use locking, for example, as follows:
+
+	struct foo {
+		int a;
+		int b;
+		int c;
+		spinlock_t lock;
+	};
+	struct foo *gp1;
+	struct foo *gp2;
+
+	void updater(void)
+	{
+		struct foo *p;
+
+		p = kmalloc(...);
+		if (p == NULL)
+			deal_with_it();
+		spin_lock(&p->lock);
+		p->a = 42;  /* Each field in its own cache line. */
+		p->b = 43;
+		p->c = 44;
+		spin_unlock(&p->lock);
+		rcu_assign_pointer(gp1, p);
+		spin_lock(&p->lock);
+		p->b = 143;
+		p->c = 144;
+		spin_unlock(&p->lock);
+		rcu_assign_pointer(gp2, p);
+	}
+
+	void reader(void)
+	{
+		struct foo *p;
+		struct foo *q;
+		int r1, r2;
+
+		p = rcu_dereference(gp2);
+		if (p == NULL)
+			return;
+		spin_lock(&p->lock);
+		r1 = p->b;  /* Guaranteed to get 143. */
+		q = rcu_dereference(gp1);  /* Guaranteed non-NULL. */
+		if (p == q) {
+			/* The compiler decides that q->c is same as p->c. */
+			r2 = p->c; /* Locking guarantees r2 == 144. */
+		}
+		spin_unlock(&p->lock);
+		do_something_with(r1, r2);
+	}
+
+As always, use the right tool for the job!
+
+
+EXAMPLE WHERE THE COMPILER KNOWS TOO MUCH
+
+If a pointer obtained from rcu_dereference() compares not-equal to some
+other pointer, the compiler normally has no clue what the value of the
+first pointer might be.  This lack of knowledge prevents the compiler
+from carrying out optimizations that otherwise might destroy the ordering
+guarantees that RCU depends on.  And the volatile cast in rcu_dereference()
+should prevent the compiler from guessing the value.
+
+But without rcu_dereference(), the compiler knows more than you might
+expect.  Consider the following code fragment:
+
+	struct foo {
+		int a;
+		int b;
+	};
+	static struct foo variable1;
+	static struct foo variable2;
+	static struct foo *gp = &variable1;
+
+	void updater(void)
+	{
+		initialize_foo(&variable2);
+		rcu_assign_pointer(gp, &variable2);
+		/*
+		 * The above is the only store to gp in this translation unit,
+		 * and the address of gp is not exported in any way.
+		 */
+	}
+
+	int reader(void)
+	{
+		struct foo *p;
+
+		p = gp;
+		barrier();
+		if (p == &variable1)
+			return p->a; /* Must be variable1.a. */
+		else
+			return p->b; /* Must be variable2.b. */
+	}
+
+Because the compiler can see all stores to "gp", it knows that the only
+possible values of "gp" are "variable1" on the one hand and "variable2"
+on the other.  The comparison in reader() therefore tells the compiler
+the exact value of "p" even in the not-equals case.  This allows the
+compiler to make the return values independent of the load from "gp",
+in turn destroying the ordering between this load and the loads of the
+return values.  This can result in "p->b" returning pre-initialization
+garbage values.
+
+In short, rcu_dereference() is -not- optional when you are going to
+dereference the resulting pointer.
+
+
+WHICH MEMBER OF THE rcu_dereference() FAMILY SHOULD YOU USE?
+
+First, please avoid using rcu_dereference_raw() and also please avoid
+using rcu_dereference_check() and rcu_dereference_protected() with a
+second argument with a constant value of 1 (or true, for that matter).
+With that caution out of the way, here is some guidance for which
+member of the rcu_dereference() to use in various situations:
+
+1.	If the access needs to be within an RCU read-side critical
+	section, use rcu_dereference().  With the new consolidated
+	RCU flavors, an RCU read-side critical section is entered
+	using rcu_read_lock(), anything that disables bottom halves,
+	anything that disables interrupts, or anything that disables
+	preemption.
+
+2.	If the access might be within an RCU read-side critical section
+	on the one hand, or protected by (say) my_lock on the other,
+	use rcu_dereference_check(), for example:
+
+		p1 = rcu_dereference_check(p->rcu_protected_pointer,
+					   lockdep_is_held(&my_lock));
+
+
+3.	If the access might be within an RCU read-side critical section
+	on the one hand, or protected by either my_lock or your_lock on
+	the other, again use rcu_dereference_check(), for example:
+
+		p1 = rcu_dereference_check(p->rcu_protected_pointer,
+					   lockdep_is_held(&my_lock) ||
+					   lockdep_is_held(&your_lock));
+
+4.	If the access is on the update side, so that it is always protected
+	by my_lock, use rcu_dereference_protected():
+
+		p1 = rcu_dereference_protected(p->rcu_protected_pointer,
+					       lockdep_is_held(&my_lock));
+
+	This can be extended to handle multiple locks as in #3 above,
+	and both can be extended to check other conditions as well.
+
+5.	If the protection is supplied by the caller, and is thus unknown
+	to this code, that is the rare case when rcu_dereference_raw()
+	is appropriate.  In addition, rcu_dereference_raw() might be
+	appropriate when the lockdep expression would be excessively
+	complex, except that a better approach in that case might be to
+	take a long hard look at your synchronization design.  Still,
+	there are data-locking cases where any one of a very large number
+	of locks or reference counters suffices to protect the pointer,
+	so rcu_dereference_raw() does have its place.
+
+	However, its place is probably quite a bit smaller than one
+	might expect given the number of uses in the current kernel.
+	Ditto for its synonym, rcu_dereference_check( ... , 1), and
+	its close relative, rcu_dereference_protected(... , 1).
+
+
+SPARSE CHECKING OF RCU-PROTECTED POINTERS
+
+The sparse static-analysis tool checks for direct access to RCU-protected
+pointers, which can result in "interesting" bugs due to compiler
+optimizations involving invented loads and perhaps also load tearing.
+For example, suppose someone mistakenly does something like this:
+
+	p = q->rcu_protected_pointer;
+	do_something_with(p->a);
+	do_something_else_with(p->b);
+
+If register pressure is high, the compiler might optimize "p" out
+of existence, transforming the code to something like this:
+
+	do_something_with(q->rcu_protected_pointer->a);
+	do_something_else_with(q->rcu_protected_pointer->b);
+
+This could fatally disappoint your code if q->rcu_protected_pointer
+changed in the meantime.  Nor is this a theoretical problem:  Exactly
+this sort of bug cost Paul E. McKenney (and several of his innocent
+colleagues) a three-day weekend back in the early 1990s.
+
+Load tearing could of course result in dereferencing a mashup of a pair
+of pointers, which also might fatally disappoint your code.
+
+These problems could have been avoided simply by making the code instead
+read as follows:
+
+	p = rcu_dereference(q->rcu_protected_pointer);
+	do_something_with(p->a);
+	do_something_else_with(p->b);
+
+Unfortunately, these sorts of bugs can be extremely hard to spot during
+review.  This is where the sparse tool comes into play, along with the
+"__rcu" marker.  If you mark a pointer declaration, whether in a structure
+or as a formal parameter, with "__rcu", which tells sparse to complain if
+this pointer is accessed directly.  It will also cause sparse to complain
+if a pointer not marked with "__rcu" is accessed using rcu_dereference()
+and friends.  For example, ->rcu_protected_pointer might be declared as
+follows:
+
+	struct foo __rcu *rcu_protected_pointer;
+
+Use of "__rcu" is opt-in.  If you choose not to use it, then you should
+ignore the sparse warnings.

Documentation/RCU/rcubarrier.rst

@@ -1,353 +0,0 @@
-.. _rcu_barrier:
-
-RCU and Unloadable Modules
-==========================
-
-[Originally published in LWN Jan. 14, 2007: http://lwn.net/Articles/217484/]
-
-RCU (read-copy update) is a synchronization mechanism that can be thought
-of as a replacement for read-writer locking (among other things), but with
-very low-overhead readers that are immune to deadlock, priority inversion,
-and unbounded latency. RCU read-side critical sections are delimited
-by rcu_read_lock() and rcu_read_unlock(), which, in non-CONFIG_PREEMPT
-kernels, generate no code whatsoever.
-
-This means that RCU writers are unaware of the presence of concurrent
-readers, so that RCU updates to shared data must be undertaken quite
-carefully, leaving an old version of the data structure in place until all
-pre-existing readers have finished. These old versions are needed because
-such readers might hold a reference to them. RCU updates can therefore be
-rather expensive, and RCU is thus best suited for read-mostly situations.
-
-How can an RCU writer possibly determine when all readers are finished,
-given that readers might well leave absolutely no trace of their
-presence? There is a synchronize_rcu() primitive that blocks until all
-pre-existing readers have completed. An updater wishing to delete an
-element p from a linked list might do the following, while holding an
-appropriate lock, of course::
-
-	list_del_rcu(p);
-	synchronize_rcu();
-	kfree(p);
-
-But the above code cannot be used in IRQ context -- the call_rcu()
-primitive must be used instead. This primitive takes a pointer to an
-rcu_head struct placed within the RCU-protected data structure and
-another pointer to a function that may be invoked later to free that
-structure. Code to delete an element p from the linked list from IRQ
-context might then be as follows::
-
-	list_del_rcu(p);
-	call_rcu(&p->rcu, p_callback);
-
-Since call_rcu() never blocks, this code can safely be used from within
-IRQ context. The function p_callback() might be defined as follows::
-
-	static void p_callback(struct rcu_head *rp)
-	{
-		struct pstruct *p = container_of(rp, struct pstruct, rcu);
-
-		kfree(p);
-	}
-
-
-Unloading Modules That Use call_rcu()
--------------------------------------
-
-But what if p_callback is defined in an unloadable module?
-
-If we unload the module while some RCU callbacks are pending,
-the CPUs executing these callbacks are going to be severely
-disappointed when they are later invoked, as fancifully depicted at
-http://lwn.net/images/ns/kernel/rcu-drop.jpg.
-
-We could try placing a synchronize_rcu() in the module-exit code path,
-but this is not sufficient. Although synchronize_rcu() does wait for a
-grace period to elapse, it does not wait for the callbacks to complete.
-
-One might be tempted to try several back-to-back synchronize_rcu()
-calls, but this is still not guaranteed to work. If there is a very
-heavy RCU-callback load, then some of the callbacks might be deferred
-in order to allow other processing to proceed. Such deferral is required
-in realtime kernels in order to avoid excessive scheduling latencies.
-
-
-rcu_barrier()
--------------
-
-We instead need the rcu_barrier() primitive.  Rather than waiting for
-a grace period to elapse, rcu_barrier() waits for all outstanding RCU
-callbacks to complete.  Please note that rcu_barrier() does **not** imply
-synchronize_rcu(), in particular, if there are no RCU callbacks queued
-anywhere, rcu_barrier() is within its rights to return immediately,
-without waiting for a grace period to elapse.
-
-Pseudo-code using rcu_barrier() is as follows:
-
-   1. Prevent any new RCU callbacks from being posted.
-   2. Execute rcu_barrier().
-   3. Allow the module to be unloaded.
-
-There is also an srcu_barrier() function for SRCU, and you of course
-must match the flavor of rcu_barrier() with that of call_rcu().  If your
-module uses multiple flavors of call_rcu(), then it must also use multiple
-flavors of rcu_barrier() when unloading that module.  For example, if
-it uses call_rcu(), call_srcu() on srcu_struct_1, and call_srcu() on
-srcu_struct_2, then the following three lines of code will be required
-when unloading::
-
- 1 rcu_barrier();
- 2 srcu_barrier(&srcu_struct_1);
- 3 srcu_barrier(&srcu_struct_2);
-
-The rcutorture module makes use of rcu_barrier() in its exit function
-as follows::
-
- 1  static void
- 2  rcu_torture_cleanup(void)
- 3  {
- 4    int i;
- 5
- 6    fullstop = 1;
- 7    if (shuffler_task != NULL) {
- 8     VERBOSE_PRINTK_STRING("Stopping rcu_torture_shuffle task");
- 9     kthread_stop(shuffler_task);
- 10   }
- 11   shuffler_task = NULL;
- 12
- 13   if (writer_task != NULL) {
- 14     VERBOSE_PRINTK_STRING("Stopping rcu_torture_writer task");
- 15     kthread_stop(writer_task);
- 16   }
- 17   writer_task = NULL;
- 18
- 19   if (reader_tasks != NULL) {
- 20     for (i = 0; i < nrealreaders; i++) {
- 21       if (reader_tasks[i] != NULL) {
- 22         VERBOSE_PRINTK_STRING(
- 23           "Stopping rcu_torture_reader task");
- 24         kthread_stop(reader_tasks[i]);
- 25       }
- 26       reader_tasks[i] = NULL;
- 27     }
- 28     kfree(reader_tasks);
- 29     reader_tasks = NULL;
- 30   }
- 31   rcu_torture_current = NULL;
- 32
- 33   if (fakewriter_tasks != NULL) {
- 34     for (i = 0; i < nfakewriters; i++) {
- 35       if (fakewriter_tasks[i] != NULL) {
- 36         VERBOSE_PRINTK_STRING(
- 37           "Stopping rcu_torture_fakewriter task");
- 38         kthread_stop(fakewriter_tasks[i]);
- 39       }
- 40       fakewriter_tasks[i] = NULL;
- 41     }
- 42     kfree(fakewriter_tasks);
- 43     fakewriter_tasks = NULL;
- 44   }
- 45
- 46   if (stats_task != NULL) {
- 47     VERBOSE_PRINTK_STRING("Stopping rcu_torture_stats task");
- 48     kthread_stop(stats_task);
- 49   }
- 50   stats_task = NULL;
- 51
- 52   /* Wait for all RCU callbacks to fire. */
- 53   rcu_barrier();
- 54
- 55   rcu_torture_stats_print(); /* -After- the stats thread is stopped! */
- 56
- 57   if (cur_ops->cleanup != NULL)
- 58     cur_ops->cleanup();
- 59   if (atomic_read(&n_rcu_torture_error))
- 60     rcu_torture_print_module_parms("End of test: FAILURE");
- 61   else
- 62     rcu_torture_print_module_parms("End of test: SUCCESS");
- 63 }
-
-Line 6 sets a global variable that prevents any RCU callbacks from
-re-posting themselves. This will not be necessary in most cases, since
-RCU callbacks rarely include calls to call_rcu(). However, the rcutorture
-module is an exception to this rule, and therefore needs to set this
-global variable.
-
-Lines 7-50 stop all the kernel tasks associated with the rcutorture
-module. Therefore, once execution reaches line 53, no more rcutorture
-RCU callbacks will be posted. The rcu_barrier() call on line 53 waits
-for any pre-existing callbacks to complete.
-
-Then lines 55-62 print status and do operation-specific cleanup, and
-then return, permitting the module-unload operation to be completed.
-
-.. _rcubarrier_quiz_1:
-
-Quick Quiz #1:
-	Is there any other situation where rcu_barrier() might
-	be required?
-
-:ref:`Answer to Quick Quiz #1 <answer_rcubarrier_quiz_1>`
-
-Your module might have additional complications. For example, if your
-module invokes call_rcu() from timers, you will need to first cancel all
-the timers, and only then invoke rcu_barrier() to wait for any remaining
-RCU callbacks to complete.
-
-Of course, if you module uses call_rcu(), you will need to invoke
-rcu_barrier() before unloading.  Similarly, if your module uses
-call_srcu(), you will need to invoke srcu_barrier() before unloading,
-and on the same srcu_struct structure.  If your module uses call_rcu()
-**and** call_srcu(), then you will need to invoke rcu_barrier() **and**
-srcu_barrier().
-
-
-Implementing rcu_barrier()
---------------------------
-
-Dipankar Sarma's implementation of rcu_barrier() makes use of the fact
-that RCU callbacks are never reordered once queued on one of the per-CPU
-queues. His implementation queues an RCU callback on each of the per-CPU
-callback queues, and then waits until they have all started executing, at
-which point, all earlier RCU callbacks are guaranteed to have completed.
-
-The original code for rcu_barrier() was as follows::
-
- 1  void rcu_barrier(void)
- 2  {
- 3    BUG_ON(in_interrupt());
- 4    /* Take cpucontrol mutex to protect against CPU hotplug */
- 5    mutex_lock(&rcu_barrier_mutex);
- 6    init_completion(&rcu_barrier_completion);
- 7    atomic_set(&rcu_barrier_cpu_count, 0);
- 8    on_each_cpu(rcu_barrier_func, NULL, 0, 1);
- 9    wait_for_completion(&rcu_barrier_completion);
- 10   mutex_unlock(&rcu_barrier_mutex);
- 11 }
-
-Line 3 verifies that the caller is in process context, and lines 5 and 10
-use rcu_barrier_mutex to ensure that only one rcu_barrier() is using the
-global completion and counters at a time, which are initialized on lines
-6 and 7. Line 8 causes each CPU to invoke rcu_barrier_func(), which is
-shown below. Note that the final "1" in on_each_cpu()'s argument list
-ensures that all the calls to rcu_barrier_func() will have completed
-before on_each_cpu() returns. Line 9 then waits for the completion.
-
-This code was rewritten in 2008 and several times thereafter, but this
-still gives the general idea.
-
-The rcu_barrier_func() runs on each CPU, where it invokes call_rcu()
-to post an RCU callback, as follows::
-
- 1  static void rcu_barrier_func(void *notused)
- 2  {
- 3    int cpu = smp_processor_id();
- 4    struct rcu_data *rdp = &per_cpu(rcu_data, cpu);
- 5    struct rcu_head *head;
- 6
- 7    head = &rdp->barrier;
- 8    atomic_inc(&rcu_barrier_cpu_count);
- 9    call_rcu(head, rcu_barrier_callback);
- 10 }
-
-Lines 3 and 4 locate RCU's internal per-CPU rcu_data structure,
-which contains the struct rcu_head that needed for the later call to
-call_rcu(). Line 7 picks up a pointer to this struct rcu_head, and line
-8 increments a global counter. This counter will later be decremented
-by the callback. Line 9 then registers the rcu_barrier_callback() on
-the current CPU's queue.
-
-The rcu_barrier_callback() function simply atomically decrements the
-rcu_barrier_cpu_count variable and finalizes the completion when it
-reaches zero, as follows::
-
- 1 static void rcu_barrier_callback(struct rcu_head *notused)
- 2 {
- 3   if (atomic_dec_and_test(&rcu_barrier_cpu_count))
- 4     complete(&rcu_barrier_completion);
- 5 }
-
-.. _rcubarrier_quiz_2:
-
-Quick Quiz #2:
-	What happens if CPU 0's rcu_barrier_func() executes
-	immediately (thus incrementing rcu_barrier_cpu_count to the
-	value one), but the other CPU's rcu_barrier_func() invocations
-	are delayed for a full grace period? Couldn't this result in
-	rcu_barrier() returning prematurely?
-
-:ref:`Answer to Quick Quiz #2 <answer_rcubarrier_quiz_2>`
-
-The current rcu_barrier() implementation is more complex, due to the need
-to avoid disturbing idle CPUs (especially on battery-powered systems)
-and the need to minimally disturb non-idle CPUs in real-time systems.
-However, the code above illustrates the concepts.
-
-
-rcu_barrier() Summary
----------------------
-
-The rcu_barrier() primitive has seen relatively little use, since most
-code using RCU is in the core kernel rather than in modules. However, if
-you are using RCU from an unloadable module, you need to use rcu_barrier()
-so that your module may be safely unloaded.
-
-
-Answers to Quick Quizzes
-------------------------
-
-.. _answer_rcubarrier_quiz_1:
-
-Quick Quiz #1:
-	Is there any other situation where rcu_barrier() might
-	be required?
-
-Answer: Interestingly enough, rcu_barrier() was not originally
-	implemented for module unloading. Nikita Danilov was using
-	RCU in a filesystem, which resulted in a similar situation at
-	filesystem-unmount time. Dipankar Sarma coded up rcu_barrier()
-	in response, so that Nikita could invoke it during the
-	filesystem-unmount process.
-
-	Much later, yours truly hit the RCU module-unload problem when
-	implementing rcutorture, and found that rcu_barrier() solves
-	this problem as well.
-
-:ref:`Back to Quick Quiz #1 <rcubarrier_quiz_1>`
-
-.. _answer_rcubarrier_quiz_2:
-
-Quick Quiz #2:
-	What happens if CPU 0's rcu_barrier_func() executes
-	immediately (thus incrementing rcu_barrier_cpu_count to the
-	value one), but the other CPU's rcu_barrier_func() invocations
-	are delayed for a full grace period? Couldn't this result in
-	rcu_barrier() returning prematurely?
-
-Answer: This cannot happen. The reason is that on_each_cpu() has its last
-	argument, the wait flag, set to "1". This flag is passed through
-	to smp_call_function() and further to smp_call_function_on_cpu(),
-	causing this latter to spin until the cross-CPU invocation of
-	rcu_barrier_func() has completed. This by itself would prevent
-	a grace period from completing on non-CONFIG_PREEMPT kernels,
-	since each CPU must undergo a context switch (or other quiescent
-	state) before the grace period can complete. However, this is
-	of no use in CONFIG_PREEMPT kernels.
-
-	Therefore, on_each_cpu() disables preemption across its call
-	to smp_call_function() and also across the local call to
-	rcu_barrier_func(). This prevents the local CPU from context
-	switching, again preventing grace periods from completing. This
-	means that all CPUs have executed rcu_barrier_func() before
-	the first rcu_barrier_callback() can possibly execute, in turn
-	preventing rcu_barrier_cpu_count from prematurely reaching zero.
-
-	Currently, -rt implementations of RCU keep but a single global
-	queue for RCU callbacks, and thus do not suffer from this
-	problem. However, when the -rt RCU eventually does have per-CPU
-	callback queues, things will have to change. One simple change
-	is to add an rcu_read_lock() before line 8 of rcu_barrier()
-	and an rcu_read_unlock() after line 8 of this same function. If
-	you can think of a better change, please let me know!
-
-:ref:`Back to Quick Quiz #2 <rcubarrier_quiz_2>`

Documentation/RCU/rcubarrier.txt

@@ -0,0 +1,325 @@
+RCU and Unloadable Modules
+
+[Originally published in LWN Jan. 14, 2007: http://lwn.net/Articles/217484/]
+
+RCU (read-copy update) is a synchronization mechanism that can be thought
+of as a replacement for read-writer locking (among other things), but with
+very low-overhead readers that are immune to deadlock, priority inversion,
+and unbounded latency. RCU read-side critical sections are delimited
+by rcu_read_lock() and rcu_read_unlock(), which, in non-CONFIG_PREEMPT
+kernels, generate no code whatsoever.
+
+This means that RCU writers are unaware of the presence of concurrent
+readers, so that RCU updates to shared data must be undertaken quite
+carefully, leaving an old version of the data structure in place until all
+pre-existing readers have finished. These old versions are needed because
+such readers might hold a reference to them. RCU updates can therefore be
+rather expensive, and RCU is thus best suited for read-mostly situations.
+
+How can an RCU writer possibly determine when all readers are finished,
+given that readers might well leave absolutely no trace of their
+presence? There is a synchronize_rcu() primitive that blocks until all
+pre-existing readers have completed. An updater wishing to delete an
+element p from a linked list might do the following, while holding an
+appropriate lock, of course:
+
+	list_del_rcu(p);
+	synchronize_rcu();
+	kfree(p);
+
+But the above code cannot be used in IRQ context -- the call_rcu()
+primitive must be used instead. This primitive takes a pointer to an
+rcu_head struct placed within the RCU-protected data structure and
+another pointer to a function that may be invoked later to free that
+structure. Code to delete an element p from the linked list from IRQ
+context might then be as follows:
+
+	list_del_rcu(p);
+	call_rcu(&p->rcu, p_callback);
+
+Since call_rcu() never blocks, this code can safely be used from within
+IRQ context. The function p_callback() might be defined as follows:
+
+	static void p_callback(struct rcu_head *rp)
+	{
+		struct pstruct *p = container_of(rp, struct pstruct, rcu);
+
+		kfree(p);
+	}
+
+
+Unloading Modules That Use call_rcu()
+
+But what if p_callback is defined in an unloadable module?
+
+If we unload the module while some RCU callbacks are pending,
+the CPUs executing these callbacks are going to be severely
+disappointed when they are later invoked, as fancifully depicted at
+http://lwn.net/images/ns/kernel/rcu-drop.jpg.
+
+We could try placing a synchronize_rcu() in the module-exit code path,
+but this is not sufficient. Although synchronize_rcu() does wait for a
+grace period to elapse, it does not wait for the callbacks to complete.
+
+One might be tempted to try several back-to-back synchronize_rcu()
+calls, but this is still not guaranteed to work. If there is a very
+heavy RCU-callback load, then some of the callbacks might be deferred
+in order to allow other processing to proceed. Such deferral is required
+in realtime kernels in order to avoid excessive scheduling latencies.
+
+
+rcu_barrier()
+
+We instead need the rcu_barrier() primitive.  Rather than waiting for
+a grace period to elapse, rcu_barrier() waits for all outstanding RCU
+callbacks to complete.  Please note that rcu_barrier() does -not- imply
+synchronize_rcu(), in particular, if there are no RCU callbacks queued
+anywhere, rcu_barrier() is within its rights to return immediately,
+without waiting for a grace period to elapse.
+
+Pseudo-code using rcu_barrier() is as follows:
+
+   1. Prevent any new RCU callbacks from being posted.
+   2. Execute rcu_barrier().
+   3. Allow the module to be unloaded.
+
+There is also an srcu_barrier() function for SRCU, and you of course
+must match the flavor of rcu_barrier() with that of call_rcu().  If your
+module uses multiple flavors of call_rcu(), then it must also use multiple
+flavors of rcu_barrier() when unloading that module.  For example, if
+it uses call_rcu(), call_srcu() on srcu_struct_1, and call_srcu() on
+srcu_struct_2(), then the following three lines of code will be required
+when unloading:
+
+ 1 rcu_barrier();
+ 2 srcu_barrier(&srcu_struct_1);
+ 3 srcu_barrier(&srcu_struct_2);
+
+The rcutorture module makes use of rcu_barrier() in its exit function
+as follows:
+
+ 1 static void
+ 2 rcu_torture_cleanup(void)
+ 3 {
+ 4   int i;
+ 5
+ 6   fullstop = 1;
+ 7   if (shuffler_task != NULL) {
+ 8     VERBOSE_PRINTK_STRING("Stopping rcu_torture_shuffle task");
+ 9     kthread_stop(shuffler_task);
+10   }
+11   shuffler_task = NULL;
+12
+13   if (writer_task != NULL) {
+14     VERBOSE_PRINTK_STRING("Stopping rcu_torture_writer task");
+15     kthread_stop(writer_task);
+16   }
+17   writer_task = NULL;
+18
+19   if (reader_tasks != NULL) {
+20     for (i = 0; i < nrealreaders; i++) {
+21       if (reader_tasks[i] != NULL) {
+22         VERBOSE_PRINTK_STRING(
+23           "Stopping rcu_torture_reader task");
+24         kthread_stop(reader_tasks[i]);
+25       }
+26       reader_tasks[i] = NULL;
+27     }
+28     kfree(reader_tasks);
+29     reader_tasks = NULL;
+30   }
+31   rcu_torture_current = NULL;
+32
+33   if (fakewriter_tasks != NULL) {
+34     for (i = 0; i < nfakewriters; i++) {
+35       if (fakewriter_tasks[i] != NULL) {
+36         VERBOSE_PRINTK_STRING(
+37           "Stopping rcu_torture_fakewriter task");
+38         kthread_stop(fakewriter_tasks[i]);
+39       }
+40       fakewriter_tasks[i] = NULL;
+41     }
+42     kfree(fakewriter_tasks);
+43     fakewriter_tasks = NULL;
+44   }
+45
+46   if (stats_task != NULL) {
+47     VERBOSE_PRINTK_STRING("Stopping rcu_torture_stats task");
+48     kthread_stop(stats_task);
+49   }
+50   stats_task = NULL;
+51
+52   /* Wait for all RCU callbacks to fire. */
+53   rcu_barrier();
+54
+55   rcu_torture_stats_print(); /* -After- the stats thread is stopped! */
+56
+57   if (cur_ops->cleanup != NULL)
+58     cur_ops->cleanup();
+59   if (atomic_read(&n_rcu_torture_error))
+60     rcu_torture_print_module_parms("End of test: FAILURE");
+61   else
+62     rcu_torture_print_module_parms("End of test: SUCCESS");
+63 }
+
+Line 6 sets a global variable that prevents any RCU callbacks from
+re-posting themselves. This will not be necessary in most cases, since
+RCU callbacks rarely include calls to call_rcu(). However, the rcutorture
+module is an exception to this rule, and therefore needs to set this
+global variable.
+
+Lines 7-50 stop all the kernel tasks associated with the rcutorture
+module. Therefore, once execution reaches line 53, no more rcutorture
+RCU callbacks will be posted. The rcu_barrier() call on line 53 waits
+for any pre-existing callbacks to complete.
+
+Then lines 55-62 print status and do operation-specific cleanup, and
+then return, permitting the module-unload operation to be completed.
+
+Quick Quiz #1: Is there any other situation where rcu_barrier() might
+	be required?
+
+Your module might have additional complications. For example, if your
+module invokes call_rcu() from timers, you will need to first cancel all
+the timers, and only then invoke rcu_barrier() to wait for any remaining
+RCU callbacks to complete.
+
+Of course, if you module uses call_rcu(), you will need to invoke
+rcu_barrier() before unloading.  Similarly, if your module uses
+call_srcu(), you will need to invoke srcu_barrier() before unloading,
+and on the same srcu_struct structure.  If your module uses call_rcu()
+-and- call_srcu(), then you will need to invoke rcu_barrier() -and-
+srcu_barrier().
+
+
+Implementing rcu_barrier()
+
+Dipankar Sarma's implementation of rcu_barrier() makes use of the fact
+that RCU callbacks are never reordered once queued on one of the per-CPU
+queues. His implementation queues an RCU callback on each of the per-CPU
+callback queues, and then waits until they have all started executing, at
+which point, all earlier RCU callbacks are guaranteed to have completed.
+
+The original code for rcu_barrier() was as follows:
+
+ 1 void rcu_barrier(void)
+ 2 {
+ 3   BUG_ON(in_interrupt());
+ 4   /* Take cpucontrol mutex to protect against CPU hotplug */
+ 5   mutex_lock(&rcu_barrier_mutex);
+ 6   init_completion(&rcu_barrier_completion);
+ 7   atomic_set(&rcu_barrier_cpu_count, 0);
+ 8   on_each_cpu(rcu_barrier_func, NULL, 0, 1);
+ 9   wait_for_completion(&rcu_barrier_completion);
+10   mutex_unlock(&rcu_barrier_mutex);
+11 }
+
+Line 3 verifies that the caller is in process context, and lines 5 and 10
+use rcu_barrier_mutex to ensure that only one rcu_barrier() is using the
+global completion and counters at a time, which are initialized on lines
+6 and 7. Line 8 causes each CPU to invoke rcu_barrier_func(), which is
+shown below. Note that the final "1" in on_each_cpu()'s argument list
+ensures that all the calls to rcu_barrier_func() will have completed
+before on_each_cpu() returns. Line 9 then waits for the completion.
+
+This code was rewritten in 2008 and several times thereafter, but this
+still gives the general idea.
+
+The rcu_barrier_func() runs on each CPU, where it invokes call_rcu()
+to post an RCU callback, as follows:
+
+ 1 static void rcu_barrier_func(void *notused)
+ 2 {
+ 3 int cpu = smp_processor_id();
+ 4 struct rcu_data *rdp = &per_cpu(rcu_data, cpu);
+ 5 struct rcu_head *head;
+ 6
+ 7 head = &rdp->barrier;
+ 8 atomic_inc(&rcu_barrier_cpu_count);
+ 9 call_rcu(head, rcu_barrier_callback);
+10 }
+
+Lines 3 and 4 locate RCU's internal per-CPU rcu_data structure,
+which contains the struct rcu_head that needed for the later call to
+call_rcu(). Line 7 picks up a pointer to this struct rcu_head, and line
+8 increments a global counter. This counter will later be decremented
+by the callback. Line 9 then registers the rcu_barrier_callback() on
+the current CPU's queue.
+
+The rcu_barrier_callback() function simply atomically decrements the
+rcu_barrier_cpu_count variable and finalizes the completion when it
+reaches zero, as follows:
+
+ 1 static void rcu_barrier_callback(struct rcu_head *notused)
+ 2 {
+ 3 if (atomic_dec_and_test(&rcu_barrier_cpu_count))
+ 4 complete(&rcu_barrier_completion);
+ 5 }
+
+Quick Quiz #2: What happens if CPU 0's rcu_barrier_func() executes
+	immediately (thus incrementing rcu_barrier_cpu_count to the
+	value one), but the other CPU's rcu_barrier_func() invocations
+	are delayed for a full grace period? Couldn't this result in
+	rcu_barrier() returning prematurely?
+
+The current rcu_barrier() implementation is more complex, due to the need
+to avoid disturbing idle CPUs (especially on battery-powered systems)
+and the need to minimally disturb non-idle CPUs in real-time systems.
+However, the code above illustrates the concepts.
+
+
+rcu_barrier() Summary
+
+The rcu_barrier() primitive has seen relatively little use, since most
+code using RCU is in the core kernel rather than in modules. However, if
+you are using RCU from an unloadable module, you need to use rcu_barrier()
+so that your module may be safely unloaded.
+
+
+Answers to Quick Quizzes
+
+Quick Quiz #1: Is there any other situation where rcu_barrier() might
+	be required?
+
+Answer: Interestingly enough, rcu_barrier() was not originally
+	implemented for module unloading. Nikita Danilov was using
+	RCU in a filesystem, which resulted in a similar situation at
+	filesystem-unmount time. Dipankar Sarma coded up rcu_barrier()
+	in response, so that Nikita could invoke it during the
+	filesystem-unmount process.
+
+	Much later, yours truly hit the RCU module-unload problem when
+	implementing rcutorture, and found that rcu_barrier() solves
+	this problem as well.
+
+Quick Quiz #2: What happens if CPU 0's rcu_barrier_func() executes
+	immediately (thus incrementing rcu_barrier_cpu_count to the
+	value one), but the other CPU's rcu_barrier_func() invocations
+	are delayed for a full grace period? Couldn't this result in
+	rcu_barrier() returning prematurely?
+
+Answer: This cannot happen. The reason is that on_each_cpu() has its last
+	argument, the wait flag, set to "1". This flag is passed through
+	to smp_call_function() and further to smp_call_function_on_cpu(),
+	causing this latter to spin until the cross-CPU invocation of
+	rcu_barrier_func() has completed. This by itself would prevent
+	a grace period from completing on non-CONFIG_PREEMPT kernels,
+	since each CPU must undergo a context switch (or other quiescent
+	state) before the grace period can complete. However, this is
+	of no use in CONFIG_PREEMPT kernels.
+
+	Therefore, on_each_cpu() disables preemption across its call
+	to smp_call_function() and also across the local call to
+	rcu_barrier_func(). This prevents the local CPU from context
+	switching, again preventing grace periods from completing. This
+	means that all CPUs have executed rcu_barrier_func() before
+	the first rcu_barrier_callback() can possibly execute, in turn
+	preventing rcu_barrier_cpu_count from prematurely reaching zero.
+
+	Currently, -rt implementations of RCU keep but a single global
+	queue for RCU callbacks, and thus do not suffer from this
+	problem. However, when the -rt RCU eventually does have per-CPU
+	callback queues, things will have to change. One simple change
+	is to add an rcu_read_lock() before line 8 of rcu_barrier()
+	and an rcu_read_unlock() after line 8 of this same function. If
+	you can think of a better change, please let me know!

Documentation/RCU/stallwarn.txt

@@ -57,12 +57,6 @@ o	A CPU-bound real-time task in a CONFIG_PREEMPT_RT kernel that
 	CONFIG_PREEMPT_RCU case, you might see stall-warning
 	messages.
 
-	You can use the rcutree.kthread_prio kernel boot parameter to
-	increase the scheduling priority of RCU's kthreads, which can
-	help avoid this problem.  However, please note that doing this
-	can increase your system's context-switch rate and thus degrade
-	performance.
-
 o	A periodic interrupt whose handler takes longer than the time
 	interval between successive pairs of interrupts.  This can
 	prevent RCU's kthreads and softirq handlers from running.
@@ -225,13 +219,18 @@ an estimate of the total number of RCU callbacks queued across all CPUs
 In kernels with CONFIG_RCU_FAST_NO_HZ, more information is printed
 for each CPU:
 
-	0: (64628 ticks this GP) idle=dd5/3fffffffffffffff/0 softirq=82/543 last_accelerate: a345/d342 dyntick_enabled: 1
+	0: (64628 ticks this GP) idle=dd5/3fffffffffffffff/0 softirq=82/543 last_accelerate: a345/d342 Nonlazy posted: ..D
 
 The "last_accelerate:" prints the low-order 16 bits (in hex) of the
 jiffies counter when this CPU last invoked rcu_try_advance_all_cbs()
 from rcu_needs_cpu() or last invoked rcu_accelerate_cbs() from
-rcu_prepare_for_idle(). "dyntick_enabled: 1" indicates that dyntick-idle
-processing is enabled.
+rcu_prepare_for_idle().  The "Nonlazy posted:" indicates lazy-callback
+status, so that an "l" indicates that all callbacks were lazy at the start
+of the last idle period and an "L" indicates that there are currently
+no non-lazy callbacks (in both cases, "." is printed otherwise, as
+shown above) and "D" indicates that dyntick-idle processing is enabled
+("." is printed otherwise, for example, if disabled via the "nohz="
+kernel boot parameter).
 
 If the grace period ends just as the stall warning starts printing,
 there will be a spurious stall-warning message, which will include