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

Pull documentation updates from Jonathan Corbet:
 "There's been a fair amount of activity in Documentation/ this time
  around:

   - Lots of work aligning Documentation/ABI with reality, done by
     Aishwarya Pant.

   - The trace documentation has been converted to RST by Changbin Du

   - I thrashed up kernel-doc to deal with a parsing issue and to try to
     make the code more readable. It's still a 20+-year-old Perl hack,
     though.

   - Lots of other updates, typo fixes, and more"

* tag 'docs-4.17' of git://git.lwn.net/linux: (82 commits)
  Documentation/process: update FUSE project website
  docs: kernel-doc: fix parsing of arrays
  dmaengine: Fix spelling for parenthesis in dmatest documentation
  dmaengine: Make dmatest.rst indeed reST compatible
  dmaengine: Add note to dmatest documentation about supported channels
  Documentation: magic-numbers: Fix typo
  Documentation: admin-guide: add kvmconfig, xenconfig and tinyconfig commands
  Input: alps - Update documentation for trackstick v3 format
  Documentation: Mention why %p prints ptrval
  COPYING: use the new text with points to the license files
  COPYING: create a new file with points to the Kernel license files
  Input: trackpoint: document sysfs interface
  xfs: Change URL for the project in xfs.txt
  char/bsr: add sysfs interface documentation
  acpi: nfit: document sysfs interface
  block: rbd: update sysfs interface
  Documentation/sparse: fix typo
  Documentation/CodingStyle: Add an example for braces
  docs/vm: update 00-INDEX
  kernel-doc: Remove __sched markings
  ...

Documentation/ABI/testing/sysfs-block-aoe

+What:		/sys/block/etherd*/mac
+Date:		Apr, 2005
+KernelVersion:	v2.6.12
+Contact:	Ed L. Cashin <ed.cashin@acm.org>
+Description:
+		(RO) The ethernet address of the remote Ata over Ethernet (AoE)
+		device.
+
+What:		/sys/block/etherd*/netif
+Date:		Apr, 2005
+KernelVersion:	v2.6.12
+Contact:	Ed L. Cashin <ed.cashin@acm.org>
+Description:
+		(RO) The names of the network interfaces on the localhost (comma
+		separated) through which we are communicating with the remote
+		AoE device.
+
+What:		/sys/block/etherd*/state
+Date:		Apr, 2005
+KernelVersion:	v2.6.12
+Contact:	Ed L. Cashin <ed.cashin@acm.org>
+Description:
+		(RO) Device status. The state attribute is "up" when the device
+		is ready for I/O and "down" if detected but unusable. The
+		"down,closewait" state shows that the device is still open and
+		cannot come up again until it has been closed.  The "up,kickme"
+		state means that the driver wants to send more commands to the
+		target but found out there were already the max number of
+		commands waiting for a response. It will retry again after being
+		kicked by the periodic timer handler routine.
+
+What:		/sys/block/etherd*/firmware-version
+Date:		Apr, 2005
+KernelVersion:	v2.6.12
+Contact:	Ed L. Cashin <ed.cashin@acm.org>
+Description:
+		(RO) Version of the firmware in the target.
+
+What:		/sys/block/etherd*/payload
+Date:		Dec, 2012
+KernelVersion:	v3.10
+Contact:	Ed L. Cashin <ed.cashin@acm.org>
+Description:
+		(RO) The amount of user data transferred (in bytes) inside each AoE
+		command on the network, network headers excluded.

Documentation/ABI/testing/sysfs-block-loop

+What:		/sys/block/loopX/loop/autoclear
+Date:		Aug, 2010
+KernelVersion:	v2.6.37
+Contact:	linux-block@vger.kernel.org
+Description:
+		(RO) Shows if the device is in autoclear mode or not ( "1" or
+		"0"). Autoclear (if set) indicates that the loopback device will
+		self-distruct after last close.
+
+What:		/sys/block/loopX/loop/backing_file
+Date:		Aug, 2010
+KernelVersion:	v2.6.37
+Contact:	linux-block@vger.kernel.org
+Description:
+		(RO) The path of the backing file that the loop device maps its
+		data blocks to.
+
+What:		/sys/block/loopX/loop/offset
+Date:		Aug, 2010
+KernelVersion:	v2.6.37
+Contact:	linux-block@vger.kernel.org
+Description:
+		(RO) Start offset (in bytes).
+
+What:		/sys/block/loopX/loop/sizelimit
+Date:		Aug, 2010
+KernelVersion:	v2.6.37
+Contact:	linux-block@vger.kernel.org
+Description:
+		(RO) The size (in bytes) that the block device maps, starting
+		from the offset.
+
+What:		/sys/block/loopX/loop/partscan
+Date:		Aug, 2011
+KernelVersion:	v3.10
+Contact:	linux-block@vger.kernel.org
+Description:
+		(RO) Shows if automatic partition scanning is enabled for the
+		device or not ("1" or "0"). This can be requested individually
+		per loop device during its setup by setting LO_FLAGS_PARTSCAN in
+		in the ioctl request. By default, no partition tables are
+		scanned.
+
+What:		/sys/block/loopX/loop/dio
+Date:		Aug, 2015
+KernelVersion:	v4.10
+Contact:	linux-block@vger.kernel.org
+Description:
+		(RO) Shows if direct IO is being used to access backing file or
+		not ("1 or "0").

Documentation/ABI/testing/sysfs-bus-nfit

+For all of the nmem device attributes under nfit/*, see the 'NVDIMM Firmware
+Interface Table (NFIT)' section in the ACPI specification
+(http://www.uefi.org/specifications) for more details.
+
+What:		/sys/bus/nd/devices/nmemX/nfit/serial
+Date:		Jun, 2015
+KernelVersion:	v4.2
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RO) Serial number of the NVDIMM (non-volatile dual in-line
+		memory module), assigned by the module vendor.
+
+
+What:		/sys/bus/nd/devices/nmemX/nfit/handle
+Date:		Apr, 2015
+KernelVersion:	v4.2
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RO) The address (given by the _ADR object) of the device on its
+		parent bus of the NVDIMM device containing the NVDIMM region.
+
+
+What:		/sys/bus/nd/devices/nmemX/nfit/device
+Date:		Apr, 2015
+KernelVersion:	v4.1
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RO) Device id for the NVDIMM, assigned by the module vendor.
+
+
+What:		/sys/bus/nd/devices/nmemX/nfit/rev_id
+Date:		Jun, 2015
+KernelVersion:	v4.2
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RO) Revision of the NVDIMM, assigned by the module vendor.
+
+
+What:		/sys/bus/nd/devices/nmemX/nfit/phys_id
+Date:		Apr, 2015
+KernelVersion:	v4.2
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RO) Handle (i.e., instance number) for the SMBIOS (system
+		management BIOS) Memory Device structure describing the NVDIMM
+		containing the NVDIMM region.
+
+
+What:		/sys/bus/nd/devices/nmemX/nfit/flags
+Date:		Jun, 2015
+KernelVersion:	v4.2
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RO) The flags in the NFIT memory device sub-structure indicate
+		the state of the data on the nvdimm relative to its energy
+		source or last "flush to persistence".
+
+		The attribute is a translation of the 'NVDIMM State Flags' field
+		in section 5.2.25.3 'NVDIMM Region Mapping' Structure of the
+		ACPI specification 6.2.
+
+		The health states are "save_fail", "restore_fail", "flush_fail",
+		"not_armed", "smart_event", "map_fail" and "smart_notify".
+
+
+What:		/sys/bus/nd/devices/nmemX/nfit/format
+What:		/sys/bus/nd/devices/nmemX/nfit/format1
+What:		/sys/bus/nd/devices/nmemX/nfit/formats
+Date:		Apr, 2016
+KernelVersion:	v4.7
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RO) The interface codes indicate support for persistent memory
+		mapped directly into system physical address space and / or a
+		block aperture access mechanism to the NVDIMM media.
+		The 'formats' attribute displays the number of supported
+		interfaces.
+
+		This layout is compatible with existing libndctl binaries that
+		only expect one code per-dimm as they will ignore
+		nmemX/nfit/formats and nmemX/nfit/formatN.
+
+
+What:		/sys/bus/nd/devices/nmemX/nfit/vendor
+Date:		Apr, 2016
+KernelVersion:	v4.7
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RO) Vendor id of the NVDIMM.
+
+
+What:		/sys/bus/nd/devices/nmemX/nfit/dsm_mask
+Date:		May, 2016
+KernelVersion:	v4.7
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RO) The bitmask indicates the supported device specific control
+		functions relative to the NVDIMM command family supported by the
+		device
+
+
+What:		/sys/bus/nd/devices/nmemX/nfit/family
+Date:		Apr, 2016
+KernelVersion:	v4.7
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RO) Displays the NVDIMM family command sets. Values
+		0, 1, 2 and 3 correspond to NVDIMM_FAMILY_INTEL,
+		NVDIMM_FAMILY_HPE1, NVDIMM_FAMILY_HPE2 and NVDIMM_FAMILY_MSFT
+		respectively.
+
+		See the specifications for these command families here:
+		http://pmem.io/documents/NVDIMM_DSM_Interface-V1.6.pdf
+		https://github.com/HewlettPackard/hpe-nvm/blob/master/Documentation/
+		https://msdn.microsoft.com/library/windows/hardware/mt604741"
+
+
+What:		/sys/bus/nd/devices/nmemX/nfit/id
+Date:		Apr, 2016
+KernelVersion:	v4.7
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RO) ACPI specification 6.2 section 5.2.25.9, defines an
+		identifier for an NVDIMM, which refelects the id attribute.
+
+
+What:		/sys/bus/nd/devices/nmemX/nfit/subsystem_vendor
+Date:		Apr, 2016
+KernelVersion:	v4.7
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RO) Sub-system vendor id of the NVDIMM non-volatile memory
+		subsystem controller.
+
+
+What:		/sys/bus/nd/devices/nmemX/nfit/subsystem_rev_id
+Date:		Apr, 2016
+KernelVersion:	v4.7
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RO) Sub-system revision id of the NVDIMM non-volatile memory subsystem
+		controller, assigned by the non-volatile memory subsystem
+		controller vendor.
+
+
+What:		/sys/bus/nd/devices/nmemX/nfit/subsystem_device
+Date:		Apr, 2016
+KernelVersion:	v4.7
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RO) Sub-system device id for the NVDIMM non-volatile memory
+		subsystem controller, assigned by the non-volatile memory
+		subsystem controller vendor.
+
+
+What:		/sys/bus/nd/devices/ndbusX/nfit/revision
+Date:		Jun, 2015
+KernelVersion:	v4.2
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RO) ACPI NFIT table revision number.
+
+
+What:		/sys/bus/nd/devices/ndbusX/nfit/scrub
+Date:		Sep, 2016
+KernelVersion:	v4.9
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RW) This shows the number of full Address Range Scrubs (ARS)
+		that have been completed since driver load time. Userspace can
+		wait on this using select/poll etc. A '+' at the end indicates
+		an ARS is in progress
+
+		Writing a value of 1 triggers an ARS scan.
+
+
+What:		/sys/bus/nd/devices/ndbusX/nfit/hw_error_scrub
+Date:		Sep, 2016
+KernelVersion:	v4.9
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RW) Provides a way to toggle the behavior between just adding
+		the address (cache line) where the MCE happened to the poison
+		list and doing a full scrub. The former (selective insertion of
+		the address) is done unconditionally.
+
+		This attribute can have the following values written to it:
+
+		'0': Switch to the default mode where an exception will only
+		insert the address of the memory error into the poison and
+		badblocks lists.
+		'1': Enable a full scrub to happen if an exception for a memory
+		error is received.
+
+
+What:		/sys/bus/nd/devices/ndbusX/nfit/dsm_mask
+Date:		Jun, 2017
+KernelVersion:	v4.13
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RO) The bitmask indicates the supported bus specific control
+		functions. See the section named 'NVDIMM Root Device _DSMs' in
+		the ACPI specification.
+
+
+What:		/sys/bus/nd/devices/regionX/nfit/range_index
+Date:		Jun, 2015
+KernelVersion:	v4.2
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RO) A unique number provided by the BIOS to identify an address
+		range. Used by NVDIMM Region Mapping Structure to uniquely refer
+		to this structure. Value of 0 is reserved and not used as an
+		index.
+
+
+What:		/sys/bus/nd/devices/regionX/nfit/ecc_unit_size
+Date:		Aug, 2017
+KernelVersion:	v4.14
+Contact:	linux-nvdimm@lists.01.org
+Description:
+		(RO) Size of a write request to a DIMM that will not incur a
+		read-modify-write cycle at the memory controller.
+
+		When the nfit driver initializes it runs an ARS (Address Range
+		Scrub) operation across every pmem range. Part of that process
+		involves determining the ARS capabilities of a given address
+		range. One of the capabilities that is reported is the 'Clear
+		Uncorrectable Error Range Length Unit Size' (see: ACPI 6.2
+		section 9.20.7.4 Function Index 1 - Query ARS Capabilities).
+		This property indicates the boundary at which the NVDIMM may
+		need to perform read-modify-write cycles to maintain ECC (Error
+		Correcting Code) blocks.

Documentation/ABI/testing/sysfs-bus-rapidio

+What:		/sys/bus/rapidio/devices/nn:d:iiii
+Description:
+		For each RapidIO device, the RapidIO subsystem creates files in
+		an individual subdirectory with the following name format of
+		device_name "nn:d:iiii", where:
+
+		nn   - two-digit hexadecimal ID of RapidIO network where the
+		       device resides
+		d    - device type: 'e' - for endpoint or 's' - for switch
+		iiii - four-digit device destID for endpoints, or switchID for
+		       switches
+
+		For example, below is a list of device directories that
+		represents a typical RapidIO network with one switch, one host,
+		and two agent endpoints, as it is seen by the enumerating host
+		(with destID = 1):
+
+		/sys/bus/rapidio/devices/00:e:0000
+		/sys/bus/rapidio/devices/00:e:0002
+		/sys/bus/rapidio/devices/00:s:0001
+
+		NOTE: An enumerating or discovering endpoint does not create a
+		sysfs entry for itself, this is why an endpoint with destID=1 is
+		not shown in the list.
+
+Attributes Common for All RapidIO Devices
+-----------------------------------------
+
+What:		/sys/bus/rapidio/devices/nn:d:iiii/did
+Date:		Nov, 2005
+KernelVersion:	v2.6.15
+Contact:	Matt Porter <mporter@kernel.crashing.org>,
+		Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+		(RO) returns the device identifier
+
+What:		/sys/bus/rapidio/devices/nn:d:iiii/vid
+Date:		Nov, 2005
+KernelVersion:	v2.6.15
+Contact:	Matt Porter <mporter@kernel.crashing.org>,
+		Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+		(RO) returns the device vendor identifier
+
+What:		/sys/bus/rapidio/devices/nn:d:iiii/device_rev
+Date:		Nov, 2005
+KernelVersion:	v2.6.15
+Contact:	Matt Porter <mporter@kernel.crashing.org>,
+		Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+		(RO) returns the device revision level
+
+What:		/sys/bus/rapidio/devices/nn:d:iiii/asm_did
+Date:		Nov, 2005
+KernelVersion:	v2.6.15
+Contact:	Matt Porter <mporter@kernel.crashing.org>,
+		Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+		(RO) returns identifier for the assembly containing the device
+
+What:		/sys/bus/rapidio/devices/nn:d:iiii/asm_rev
+Date:		Nov, 2005
+KernelVersion:	v2.6.15
+Contact:	Matt Porter <mporter@kernel.crashing.org>,
+		Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+		(RO) returns revision level of the assembly containing the
+		device
+
+What:		/sys/bus/rapidio/devices/nn:d:iiii/asm_vid
+Date:		Nov, 2005
+KernelVersion:	v2.6.15
+Contact:	Matt Porter <mporter@kernel.crashing.org>,
+		Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+		(RO) returns vendor identifier of the assembly containing the
+		device
+
+What:		/sys/bus/rapidio/devices/nn:d:iiii/destid
+Date:		Mar, 2011
+KernelVersion:	v2.6.3
+Contact:	Matt Porter <mporter@kernel.crashing.org>,
+		Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+		(RO) returns device destination ID assigned by the enumeration
+		routine
+
+What:		/sys/bus/rapidio/devices/nn:d:iiii/lprev
+Date:		Mar, 2011
+KernelVersion:	v2.6.39
+Contact:	Matt Porter <mporter@kernel.crashing.org>,
+		Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+		(RO) returns name of previous device (switch) on the path to the
+		device that that owns this attribute
+
+What:		/sys/bus/rapidio/devices/nn:d:iiii/modalias
+Date:		Jul, 2013
+KernelVersion:	v3.11
+Contact:	Matt Porter <mporter@kernel.crashing.org>,
+		Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+		(RO) returns the device modalias
+
+What:		/sys/bus/rapidio/devices/nn:d:iiii/config
+Date:		Nov, 2005
+KernelVersion:	v2.6.15
+Contact:	Matt Porter <mporter@kernel.crashing.org>,
+		Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+		(RW) Binary attribute to read from and write to the device
+		configuration registers using the RapidIO maintenance
+		transactions. This attribute is similar in behaviour to the
+		"config" attribute of PCI devices and provides an access to the
+		RapidIO device registers using standard file read and write
+		operations.
+
+RapidIO Switch Device Attributes
+--------------------------------
+
+RapidIO switches have additional attributes in sysfs. RapidIO subsystem supports
+common and device-specific sysfs attributes for switches. Because switches are
+integrated into the RapidIO subsystem, it offers a method to create
+device-specific sysfs attributes by specifying a callback function that may be
+set by the switch initialization routine during enumeration or discovery
+process.
+
+What:		/sys/bus/rapidio/devices/nn:s:iiii/routes
+Date:		Nov, 2005
+KernelVersion:	v2.6.15
+Contact:	Matt Porter <mporter@kernel.crashing.org>,
+		Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+		(RO) reports switch routing information in "destID port" format.
+		This attribute reports only valid routing table entries, one
+		line for each entry.
+
+What:		/sys/bus/rapidio/devices/nn:s:iiii/destid
+Date:		Mar, 2011
+KernelVersion:	v2.6.3
+Contact:	Matt Porter <mporter@kernel.crashing.org>,
+		Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+		(RO) device destination ID of the associated device that defines
+		a route to the switch
+
+What:		/sys/bus/rapidio/devices/nn:s:iiii/hopcount
+Date:		Mar, 2011
+KernelVersion:	v2.6.39
+Contact:	Matt Porter <mporter@kernel.crashing.org>,
+		Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+		(RO) number of hops on the path to the switch
+
+What:		/sys/bus/rapidio/devices/nn:s:iiii/lnext
+Date:		Mar, 2011
+KernelVersion:	v2.6.39
+Contact:	Matt Porter <mporter@kernel.crashing.org>,
+		Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+		(RO) returns names of devices linked to the switch except one of
+		a device linked to the ingress port (reported as "lprev"). This
+		is an array names with number of lines equal to number of ports
+		in switch. If a switch port has no attached device, returns
+		"null" instead of a device name.
+
+Device-specific Switch Attributes
+---------------------------------
+
+IDT_GEN2-
+
+What:		/sys/bus/rapidio/devices/nn:s:iiii/errlog
+Date:		Oct, 2010
+KernelVersion:	v2.6.37
+Contact:	Matt Porter <mporter@kernel.crashing.org>,
+		Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+		(RO) reads contents of device error log until it is empty.
+
+RapidIO Bus Attributes
+----------------------
+
+What:		/sys/bus/rapidio/scan
+Date:		May, 2013
+KernelVersion:	v3.11
+Contact:	Matt Porter <mporter@kernel.crashing.org>,
+		Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+		(WO) Allows to trigger enumeration discovery process from user
+		space. To initiate an enumeration or discovery process on
+		specific mport device, a user needs to write mport_ID (not
+		RapidIO destination ID) into this file. The mport_ID is a
+		sequential number (0 ...  RIO_MAX_MPORTS) assigned to the mport
+		device. For example, for a machine with a single RapidIO
+		controller, mport_ID for that controller always will be 0. To
+		initiate RapidIO enumeration/discovery on all available mports a
+		user must write '-1' (or RIO_MPORT_ANY) into this attribute
+		file.

Documentation/ABI/testing/sysfs-bus-rbd

-What:		/sys/bus/rbd/
-Date:		November 2010
-Contact:	Yehuda Sadeh <yehuda@newdream.net>,
-		Sage Weil <sage@newdream.net>
+What:		/sys/bus/rbd/add
+Date:		Oct, 2010
+KernelVersion:	v2.6.37
+Contact:	Sage Weil <sage@newdream.net>
 Description:
+		(WO) Add rbd block device.
 
-Being used for adding and removing rbd block devices.
-
-Usage: <mon ip addr> <options> <pool name> <rbd image name> [<snap name>]
+		Usage: <mon ip addr> <options> <pool name> <rbd image name> [<snap name>]
 
 		 $ echo "192.168.0.1 name=admin rbd foo" > /sys/bus/rbd/add
 
-The snapshot name can be "-" or omitted to map the image read/write. A <dev-id>
-will be assigned for any registered block device. If snapshot is used, it will
-be mapped read-only.
+		The snapshot name can be "-" or omitted to map the image
+		read/write. A <dev-id> will be assigned for any registered block
+		device. If snapshot is used, it will be mapped read-only.
+
+
+What:		/sys/bus/rbd/remove
+Date:		Oct, 2010
+KernelVersion:	v2.6.37
+Contact:	Sage Weil <sage@newdream.net>
+Description:
+		(WO) Remove rbd block device.
 
-Usage: <dev-id> [force]
+		Usage: <dev-id> [force]
 
 		 $ echo 2 > /sys/bus/rbd/remove
 
-Optional "force" argument which when passed will wait for running requests and
-then unmap the image. Requests sent to the driver after initiating the removal
-will be failed.  (August 2016, since 4.9.)
+		Optional "force" argument which when passed will wait for
+		running requests and then unmap the image. Requests sent to the
+		driver after initiating the removal will be failed. (August
+		2016, since 4.9.)
+
 
 What:		/sys/bus/rbd/add_single_major
-Date:		December 2013
-KernelVersion:	3.14
-Contact:	Sage Weil <sage@inktank.com>
-Description:	Available only if rbd module is inserted with single_major
+Date:		Dec, 2013
+KernelVersion:	v3.14
+Contact:	Sage Weil <sage@newdream.net>
+Description:
+		(WO) Available only if rbd module is inserted with single_major
 		parameter set to true.
-		Usage is the same as for /sys/bus/rbd/add.  If present,
+
+		Usage is the same as for /sys/bus/rbd/add. If present, this
 		should be used instead of the latter: any attempts to use
-		/sys/bus/rbd/add if /sys/bus/rbd/add_single_major is
-		available will fail for backwards compatibility reasons.
+		/sys/bus/rbd/add if /sys/bus/rbd/add_single_major is available
+		will fail for backwards compatibility reasons.
+
 
 What:		/sys/bus/rbd/remove_single_major
-Date:		December 2013
-KernelVersion:	3.14
-Contact:	Sage Weil <sage@inktank.com>
-Description:	Available only if rbd module is inserted with single_major
+Date:		Dec, 2013
+KernelVersion:	v3.14
+Contact:	Sage Weil <sage@newdream.net>
+Description:
+		(WO) Available only if rbd module is inserted with single_major
 		parameter set to true.
-		Usage is the same as for /sys/bus/rbd/remove.  If present,
+
+		Usage is the same as for /sys/bus/rbd/remove. If present, this
 		should be used instead of the latter: any attempts to use
 		/sys/bus/rbd/remove if /sys/bus/rbd/remove_single_major is
 		available will fail for backwards compatibility reasons.
 
-Entries under /sys/bus/rbd/devices/<dev-id>/
---------------------------------------------
-
-client_addr
-
-	The ceph unique client entity_addr_t (address + nonce).
-	The format is <address>:<port>/<nonce>: '1.2.3.4:1234/5678' or
-	'[1:2:3:4:5:6:7:8]:1234/5678'.  (August 2016, since 4.9.)
-
-client_id
-
-	The ceph unique client id that was assigned for this specific session.
 
-cluster_fsid
-
-	The ceph cluster UUID.  (August 2016, since 4.9.)
-
-config_info
-
-	The string written into /sys/bus/rbd/add{,_single_major}.  (August
-	2016, since 4.9.)
-
-features
-
-	A hexadecimal encoding of the feature bits for this image.
-
-major
-
-	The block device major number.
+What:		/sys/bus/rbd/supported_features
+Date:		Mar, 2017
+KernelVersion:	v4.11
+Contact:	Sage Weil <sage@newdream.net>
+Description:
+		(RO) Displays the features supported by the rbd module so that
+		userspace can generate meaningful error messages and spell out
+		unsupported features that need to be disabled.
+
+
+What:		/sys/bus/rbd/devices/<dev-id>/size
+What:		/sys/bus/rbd/devices/<dev-id>/major
+What:		/sys/bus/rbd/devices/<dev-id>/client_id
+What:		/sys/bus/rbd/devices/<dev-id>/pool
+What:		/sys/bus/rbd/devices/<dev-id>/name
+What:		/sys/bus/rbd/devices/<dev-id>/refresh
+What:		/sys/bus/rbd/devices/<dev-id>/current_snap
+Date:		Oct, 2010
+KernelVersion:	v2.6.37
+Contact:	Sage Weil <sage@newdream.net>
+Description:
+		size:		(RO) The size (in bytes) of the mapped block
+				device.
 
-minor
+		major:		(RO) The block device major number.
 
-	The block device minor number.  (December 2013, since 3.14.)
+		client_id:	(RO) The ceph unique client id that was assigned
+				for this specific session.
 
-name
+		pool:		(RO) The name of the storage pool where this rbd
+				image resides. An rbd image name is unique
+				within its pool.
 
-	The name of the rbd image.
+		name:		(RO) The name of the rbd image.
 
-image_id
+		refresh:	(WO) Writing to this file will reread the image
+				header data and set all relevant data structures
+				accordingly.
 
-	The unique id for the rbd image.  (For rbd image format 1
-	this is empty.)
+		current_snap:	(RO) The current snapshot for which the device
+				is mapped.
 
-pool
 
-	The name of the storage pool where this rbd image resides.
-	An rbd image name is unique within its pool.
+What:		/sys/bus/rbd/devices/<dev-id>/pool_id
+Date:		Jul, 2012
+KernelVersion:	v3.6
+Contact:	Sage Weil <sage@newdream.net>
+Description:
+		(RO) The unique identifier for the rbd image's pool. This is a
+		permanent attribute of the pool. A pool's id will never change.
 
-pool_id
 
-	The unique identifier for the rbd image's pool.  This is
-	a permanent attribute of the pool.  A pool's id will never
-	change.
+What:		/sys/bus/rbd/devices/<dev-id>/image_id
+What:		/sys/bus/rbd/devices/<dev-id>/features
+Date:		Oct, 2012
+KernelVersion:	v3.7
+Contact:	Sage Weil <sage@newdream.net>
+Description:
+		image_id:	(RO) The unique id for the rbd image. (For rbd
+				image format 1 this is empty.)
 
-size
+		features:	(RO) A hexadecimal encoding of the feature bits
+				for this image.
 
-	The size (in bytes) of the mapped block device.
 
-refresh
+What:		/sys/bus/rbd/devices/<dev-id>/parent
+Date:		Nov, 2012
+KernelVersion:	v3.8
+Contact:	Sage Weil <sage@newdream.net>
+Description:
+		(RO) Information identifying the chain of parent images in a
+		layered rbd image. Entries are separated by empty lines.
 
-	Writing to this file will reread the image header data and set
-	all relevant datastructures accordingly.
 
-current_snap
+What:		/sys/bus/rbd/devices/<dev-id>/minor
+Date:		Dec, 2013
+KernelVersion:	v3.14
+Contact:	Sage Weil <sage@newdream.net>
+Description:
+		(RO) The block device minor number.
 
-	The current snapshot for which the device is mapped.
 
-snap_id
+What:		/sys/bus/rbd/devices/<dev-id>/snap_id
+What:		/sys/bus/rbd/devices/<dev-id>/config_info
+What:		/sys/bus/rbd/devices/<dev-id>/cluster_fsid
+What:		/sys/bus/rbd/devices/<dev-id>/client_addr
+Date:		Aug, 2016
+KernelVersion:	v4.9
+Contact:	Sage Weil <sage@newdream.net>
+Description:
+		snap_id:	(RO) The current snapshot's id.
 
-	The current snapshot's id.  (August 2016, since 4.9.)
+		config_info:	(RO) The string written into
+				/sys/bus/rbd/add{,_single_major}.
 
-parent
+		cluster_fsid:	(RO) The ceph cluster UUID.
 
-	Information identifying the chain of parent images in a layered rbd
-	image.  Entries are separated by empty lines.
+		client_addr:	(RO) The ceph unique client
+				entity_addr_t (address + nonce). The format is
+				<address>:<port>/<nonce>: '1.2.3.4:1234/5678' or
+				'[1:2:3:4:5:6:7:8]:1234/5678'.

Documentation/ABI/testing/sysfs-class-backlight-adp5520

+sysfs interface for analog devices adp5520(01) backlight driver
+---------------------------------------------------------------
+
+The backlight brightness control operates at three different levels for the
+adp5520 and adp5501 devices: daylight (level 1), office (level 2) and dark
+(level 3). By default the brightness operates at the daylight brightness level.
+
+What:		/sys/class/backlight/<backlight>/daylight_max
+What:		/sys/class/backlight/<backlight>/office_max
+What:		/sys/class/backlight/<backlight>/dark_max
+Date:		Sep, 2009
+KernelVersion:	v2.6.32
+Contact:	Michael Hennerich <michael.hennerich@analog.com>
+Description:
+		(RW) Maximum current setting for the backlight when brightness
+		is at one of the three levels (daylight, office or dark). This
+		is an input code between 0 and 127, which is transformed to a
+		value between 0 mA and 30 mA using linear or non-linear
+		algorithms.
+
+What:		/sys/class/backlight/<backlight>/daylight_dim
+What:		/sys/class/backlight/<backlight>/office_dim
+What:		/sys/class/backlight/<backlight>/dark_dim
+Date:		Sep, 2009
+KernelVersion:	v2.6.32
+Contact:	Michael Hennerich <michael.hennerich@analog.com>
+Description:
+		(RW) Dim current setting for the backlight when brightness is at
+		one of the three levels (daylight, office or dark). This is an
+		input code between 0 and 127, which is transformed to a value
+		between 0 mA and 30 mA using linear or non-linear algorithms.

Documentation/ABI/testing/sysfs-class-backlight-adp8860

+sysfs interface for analog devices adp8860 backlight driver
+-----------------------------------------------------------
+
+The backlight brightness control operates at three different levels for the
+adp8860, adp8861 and adp8863 devices: daylight (level 1), office (level 2) and
+dark (level 3). By default the brightness operates at the daylight brightness
+level.
+
+What:		/sys/class/backlight/<backlight>/ambient_light_level
+Date:		Apr, 2010
+KernelVersion:	v2.6.35
+Contact:	Michael Hennerich <michael.hennerich@analog.com>
+Description:
+		(RO) 13-bit conversion value for the first light sensor—high
+		byte (Bit 12 to Bit 8). The value is updated every 80 ms (when
+		the light sensor is enabled).
+
+
+What:		/sys/class/backlight/<backlight>/ambient_light_zone
+Date:		Apr, 2010
+KernelVersion:	v2.6.35
+Contact:	Michael Hennerich <michael.hennerich@analog.com>
+Description:
+		(RW) Read or write the specific level at which the backlight
+		operates. Value "0" enables automatic ambient light sensing, and
+		values "1", "2" or "3" set the control to daylight, office or
+		dark respectively.
+
+
+What:		/sys/class/backlight/<backlight>/l1_daylight_max
+What:		/sys/class/backlight/<backlight>/l2_office_max
+What:		/sys/class/backlight/<backlight>/l3_dark_max
+Date:		Apr, 2010
+KernelVersion:	v2.6.35
+Contact:	Michael Hennerich <michael.hennerich@analog.com>
+Description:
+		(RW) Maximum current setting for the backlight when brightness
+		is at one of the three levels (daylight, office or dark). This
+		is an input code between 0 and 127, which is transformed to a
+		value between 0 mA and 30 mA using linear or non-linear
+		algorithms.
+
+
+What:		/sys/class/backlight/<backlight>/l1_daylight_dim
+What:		/sys/class/backlight/<backlight>/l2_office_dim
+What:		/sys/class/backlight/<backlight>/l3_dark_dim
+Date:		Apr, 2010
+KernelVersion:	v2.6.35
+Contact:	Michael Hennerich <michael.hennerich@analog.com>
+Description:
+		(RW) Dim current setting for the backlight when brightness is at
+		one of the three levels (daylight, office or dark). This is an
+		input code between 0 and 127, which is transformed to a value
+		between 0 mA and 30 mA using linear or non-linear algorithms.

Documentation/ABI/testing/sysfs-class-backlight-lm3639

+sysfs interface for Texas Instruments lm3639 backlight + flash led driver chip
+------------------------------------------------------------------------------
+
+What:		/sys/class/backlight/<backlight>/bled_mode
+Date:		Oct, 2012
+KernelVersion:	v3.10
+Contact:	dri-devel@lists.freedesktop.org
+Description:
+		(WO) Write to the backlight mapping mode. The backlight current
+		can be mapped for either exponential (value "0") or linear
+		mapping modes (default).

Documentation/ABI/testing/sysfs-class-bsr

+What:		/sys/class/bsr/bsr*/bsr_size
+Date:		Jul, 2008
+KernelVersion:	2.6.27
+Contact:	Arnd Bergmann <arnd@arndb.de>,
+		Greg Kroah-Hartman <gregkh@linuxfoundation.org>
+Description:
+		(RO) Size of the barrier-synchronization register (BSR)
+		register in bytes.
+
+What:		/sys/class/bsr/bsr*/bsr_length
+Date:		Jul, 2008
+KernelVersion:	2.6.27
+Contact:	Arnd Bergmann <arnd@arndb.de>,
+		Greg Kroah-Hartman <gregkh@linuxfoundation.org>
+Description:
+		(RO) The length of memory region that can be mapped in bytes.
+
+What:		/sys/class/bsr/bsr*/bsr_stride
+Date:		Jul, 2008
+KernelVersion:	2.6.27
+Contact:	Arnd Bergmann <arnd@arndb.de>,
+		Greg Kroah-Hartman <gregkh@linuxfoundation.org>
+Description:
+		(RO) The stride or the interval at which the allocated BSR bytes
+		repeat within the mapping.

Documentation/ABI/testing/sysfs-class-infiniband

-What:		/sys/class/infiniband/<hca>/ports/<port-number>/gid_attrs/ndevs/<gid-index>
-Date:		November 29, 2015
-KernelVersion:	4.4.0
-Contact:	linux-rdma@vger.kernel.org
-Description: 	The net-device's name associated with the GID resides
-		at index <gid-index>.
-
-What:		/sys/class/infiniband/<hca>/ports/<port-number>/gid_attrs/types/<gid-index>
-Date:		November 29, 2015
-KernelVersion:	4.4.0
-Contact:	linux-rdma@vger.kernel.org
-Description: 	The RoCE type of the associated GID resides at index <gid-index>.
-		This could either be "IB/RoCE v1" for IB and RoCE v1 based GODs
-		or "RoCE v2" for RoCE v2 based GIDs.
-
-

Documentation/ABI/testing/sysfs-class-lcd-s6e63m0

+sysfs interface for the S6E63M0 AMOLED LCD panel driver
+-------------------------------------------------------
+
+What:		/sys/class/lcd/<lcd>/gamma_mode
+Date:		May, 2010
+KernelVersion:	v2.6.35
+Contact:	dri-devel@lists.freedesktop.org
+Description:
+		(RW) Read or write the gamma mode. Following three modes are
+		supported:
+		0 - gamma value 2.2,
+		1 - gamma value 1.9 and
+		2 - gamma value 1.7.
+
+
+What:		/sys/class/lcd/<lcd>/gamma_table
+Date:		May, 2010
+KernelVersion:	v2.6.35
+Contact:	dri-devel@lists.freedesktop.org
+Description:
+		(RO) Displays the size of the gamma table i.e. the number of
+		gamma modes available.
+
+This is a backlight lcd driver. These interfaces are an extension to the API
+documented in Documentation/ABI/testing/sysfs-class-lcd and in
+Documentation/ABI/stable/sysfs-class-backlight (under
+/sys/class/backlight/<backlight>/).

Documentation/ABI/testing/sysfs-class-pktcdvd

-What:           /sys/class/pktcdvd/
+sysfs interface
+---------------
+The pktcdvd module (packet writing driver) creates the following files in the
+sysfs: (<devid> is in the format major:minor)
+
+What:		/sys/class/pktcdvd/add
+What:		/sys/class/pktcdvd/remove
+What:		/sys/class/pktcdvd/device_map
 Date:		Oct. 2006
 KernelVersion:	2.6.20
 Contact:	Thomas Maier <balagi@justmail.de>
 Description:
 
-sysfs interface
----------------
+		add:		(WO) Write a block device id (major:minor) to
+				create a new pktcdvd device and map it to the
+				block device.
 
-The pktcdvd module (packet writing driver) creates
-these files in the sysfs:
-(<devid> is in format  major:minor )
+		remove:		(WO) Write the pktcdvd device id (major:minor)
+				to remove the pktcdvd device.
 
-/sys/class/pktcdvd/
-    add            (0200)  Write a block device id (major:minor)
-                           to create a new pktcdvd device and map
-                           it to the block device.
+		device_map:	(RO) Shows the device mapping in format:
+				pktcdvd[0-7] <pktdevid> <blkdevid>
 
-    remove         (0200)  Write the pktcdvd device id (major:minor)
-                           to it to remove the pktcdvd device.
 
-    device_map     (0444)  Shows the device mapping in format:
-                             pktcdvd[0-7] <pktdevid> <blkdevid>
+What:		/sys/class/pktcdvd/pktcdvd[0-7]/dev
+What:		/sys/class/pktcdvd/pktcdvd[0-7]/uevent
+Date:		Oct. 2006
+KernelVersion:	2.6.20
+Contact:	Thomas Maier <balagi@justmail.de>
+Description:
+		dev:	(RO) Device id
+
+		uevent:	(WO) To send a uevent
+
 
-/sys/class/pktcdvd/pktcdvd[0-7]/
-    dev                   (0444) Device id
-    uevent                (0200) To send an uevent.
+What:		/sys/class/pktcdvd/pktcdvd[0-7]/stat/packets_started
+What:		/sys/class/pktcdvd/pktcdvd[0-7]/stat/packets_finished
+What:		/sys/class/pktcdvd/pktcdvd[0-7]/stat/kb_written
+What:		/sys/class/pktcdvd/pktcdvd[0-7]/stat/kb_read
+What:		/sys/class/pktcdvd/pktcdvd[0-7]/stat/kb_read_gather
+What:		/sys/class/pktcdvd/pktcdvd[0-7]/stat/reset
+Date:		Oct. 2006
+KernelVersion:	2.6.20
+Contact:	Thomas Maier <balagi@justmail.de>
+Description:
+		packets_started:	(RO) Number of started packets.
 
-/sys/class/pktcdvd/pktcdvd[0-7]/stat/
-    packets_started       (0444) Number of started packets.
-    packets_finished      (0444) Number of finished packets.
+		packets_finished:	(RO) Number of finished packets.
 
-    kb_written            (0444) kBytes written.
-    kb_read               (0444) kBytes read.
-    kb_read_gather        (0444) kBytes read to fill write packets.
+		kb_written:		(RO) kBytes written.
 
-    reset                 (0200) Write any value to it to reset
+		kb_read:		(RO) kBytes read.
+
+		kb_read_gather:		(RO) kBytes read to fill write packets.
+
+		reset:			(WO) Write any value to it to reset
 					pktcdvd device statistic values, like
 					bytes read/written.
 
-/sys/class/pktcdvd/pktcdvd[0-7]/write_queue/
-    size                  (0444) Contains the size of the bio write
-                                 queue.
-
-    congestion_off        (0644) If bio write queue size is below
-                                 this mark, accept new bio requests
-                                 from the block layer.
-
-    congestion_on         (0644) If bio write queue size is higher
-                                 as this mark, do no longer accept
-                                 bio write requests from the block
-                                 layer and wait till the pktcdvd
-                                 device has processed enough bio's
-                                 so that bio write queue size is
-                                 below congestion off mark.
-                                 A value of <= 0 disables congestion
-                                 control.
+
+What:		/sys/class/pktcdvd/pktcdvd[0-7]/write_queue/size
+What:		/sys/class/pktcdvd/pktcdvd[0-7]/write_queue/congestion_off
+What:		/sys/class/pktcdvd/pktcdvd[0-7]/write_queue/congestion_on
+Date:		Oct. 2006
+KernelVersion:	2.6.20
+Contact:	Thomas Maier <balagi@justmail.de>
+Description:
+		size:		(RO) Contains the size of the bio write queue.
+
+		congestion_off:	(RW) If bio write queue size is below this mark,
+				accept new bio requests from the block layer.
+
+		congestion_on:	(RW) If bio write queue size is higher as this
+				mark, do no longer accept bio write requests
+				from the block layer and wait till the pktcdvd
+				device has processed enough bio's so that bio
+				write queue size is below congestion off mark.
+				A value of <= 0 disables congestion control.
 
 
 Example:

Documentation/ABI/testing/sysfs-class-rapidio

+What:		/sys/class/rapidio_port
+Description:
+		On-chip RapidIO controllers and PCIe-to-RapidIO bridges
+		(referenced as "Master Port" or "mport") are presented in sysfs
+		as the special class of devices: "rapidio_port".
+		The /sys/class/rapidio_port subdirectory contains individual
+		subdirectories named as "rapidioN" where N = mport ID registered
+		with RapidIO subsystem.
+		NOTE: An mport ID is not a RapidIO destination ID assigned to a
+		given local mport device.
+
+What:		/sys/class/rapidio_port/rapidioN/sys_size
+Date:		Apr, 2014
+KernelVersion:	v3.15
+Contact:	Matt Porter <mporter@kernel.crashing.org>,
+		Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+		(RO) reports RapidIO common transport system size:
+		0 = small (8-bit destination ID, max. 256 devices),
+		1 = large (16-bit destination ID, max. 65536 devices).
+
+What:		/sys/class/rapidio_port/rapidioN/port_destid
+Date:		Apr, 2014
+KernelVersion:	v3.15
+Contact:	Matt Porter <mporter@kernel.crashing.org>,
+		Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+		(RO) reports RapidIO destination ID assigned to the given
+		RapidIO mport device. If value 0xFFFFFFFF is returned this means
+		that no valid destination ID have been assigned to the mport
+		(yet). Normally, before enumeration/discovery have been executed
+		only fabric enumerating mports have a valid destination ID
+		assigned to them using "hdid=..." rapidio module parameter.
+
+After enumeration or discovery was performed for a given mport device,
+the corresponding subdirectory will also contain subdirectories for each
+child RapidIO device connected to the mport.
+
+The example below shows mport device subdirectory with several child RapidIO
+devices attached to it.
+
+[rio@rapidio ~]$ ls /sys/class/rapidio_port/rapidio0/ -l
+total 0
+drwxr-xr-x 3 root root    0 Feb 11 15:10 00:e:0001
+drwxr-xr-x 3 root root    0 Feb 11 15:10 00:e:0004
+drwxr-xr-x 3 root root    0 Feb 11 15:10 00:e:0007
+drwxr-xr-x 3 root root    0 Feb 11 15:10 00:s:0002
+drwxr-xr-x 3 root root    0 Feb 11 15:10 00:s:0003
+drwxr-xr-x 3 root root    0 Feb 11 15:10 00:s:0005
+lrwxrwxrwx 1 root root    0 Feb 11 15:11 device -> ../../../0000:01:00.0
+-r--r--r-- 1 root root 4096 Feb 11 15:11 port_destid
+drwxr-xr-x 2 root root    0 Feb 11 15:11 power
+lrwxrwxrwx 1 root root    0 Feb 11 15:04 subsystem -> ../../../../../../class/rapidio_port
+-r--r--r-- 1 root root 4096 Feb 11 15:11 sys_size
+-rw-r--r-- 1 root root 4096 Feb 11 15:04 uevent

Documentation/ABI/testing/sysfs-devices-platform-trackpoint

+What:		/sys/devices/platform/i8042/.../sensitivity
+Date:		Aug, 2005
+KernelVersion:	2.6.14
+Contact:	linux-input@vger.kernel.org
+Description:
+		(RW) Trackpoint sensitivity.
+
+What:		/sys/devices/platform/i8042/.../intertia
+Date:		Aug, 2005
+KernelVersion:	2.6.14
+Contact:	linux-input@vger.kernel.org
+Description:
+		(RW) Negative inertia factor. High values cause the cursor to
+		snap backward when the trackpoint is released.
+
+What:		/sys/devices/platform/i8042/.../reach
+Date:		Aug, 2005
+KernelVersion:	2.6.14
+Contact:	linux-input@vger.kernel.org
+Description:
+		(RW) Backup range for z-axis press.
+
+What:		/sys/devices/platform/i8042/.../draghys
+Date:		Aug, 2005
+KernelVersion:	2.6.14
+Contact:	linux-input@vger.kernel.org
+Description:
+		(RW) The drag hysteresis controls how hard it is to drag with
+		z-axis pressed.
+
+What:		/sys/devices/platform/i8042/.../mindrag
+Date:		Aug, 2005
+KernelVersion:	2.6.14
+Contact:	linux-input@vger.kernel.org
+Description:
+		(RW) Minimum amount of force needed to trigger dragging.
+
+What:		/sys/devices/platform/i8042/.../speed
+Date:		Aug, 2005
+KernelVersion:	2.6.14
+Contact:	linux-input@vger.kernel.org
+Description:
+		(RW) Speed of the trackpoint cursor.
+
+What:		/sys/devices/platform/i8042/.../thresh
+Date:		Aug, 2005
+KernelVersion:	2.6.14
+Contact:	linux-input@vger.kernel.org
+Description:
+		(RW) Minimum value for z-axis force required to trigger a press
+		or release, relative to the running average.
+
+What:		/sys/devices/platform/i8042/.../upthresh
+Date:		Aug, 2005
+KernelVersion:	2.6.14
+Contact:	linux-input@vger.kernel.org
+Description:
+		(RW) The offset from the running average required to generate a
+		select (click) on z-axis on release.
+
+What:		/sys/devices/platform/i8042/.../ztime
+Date:		Aug, 2005
+KernelVersion:	2.6.14
+Contact:	linux-input@vger.kernel.org
+Description:
+		(RW) This attribute determines how sharp a press has to be in
+		order to be recognized.
+
+What:		/sys/devices/platform/i8042/.../jenks
+Date:		Aug, 2005
+KernelVersion:	2.6.14
+Contact:	linux-input@vger.kernel.org
+Description:
+		(RW) Minimum curvature in degrees required to generate a double
+		click without a release.
+
+What:		/sys/devices/platform/i8042/.../skipback
+Date:		Aug, 2005
+KernelVersion:	2.6.14
+Contact:	linux-input@vger.kernel.org
+Description:
+		(RW) When the skipback bit is set, backup cursor movement during
+		releases from drags will be suppressed. The default value for
+		this bit is 0.
+
+What:		/sys/devices/platform/i8042/.../ext_dev
+Date:		Aug, 2005
+KernelVersion:	2.6.14
+Contact:	linux-input@vger.kernel.org
+Description:
+		(RW) Disable (0) or enable (1) external pointing device.
+
+What:		/sys/devices/platform/i8042/.../press_to_select
+Date:		Aug, 2005
+KernelVersion:	2.6.14
+Contact:	linux-input@vger.kernel.org
+Description:
+		(RW) Writing a value of 1 to this file will enable the Press to
+		Select functions like tapping the control stick to simulate a
+		left click, and writing 0 will disable it.
+
+What:		/sys/devices/platform/i8042/.../drift_time
+Date:		Dec, 2014
+KernelVersion:	3.19
+Contact:	linux-input@vger.kernel.org
+Description:
+		(RW) This parameter controls the period of time to test for a
+		‘hands off’ condition (i.e. when no force is applied) before a
+		drift (noise) calibration occurs.
+
+		IBM Trackpoints have a feature to compensate for drift by
+		recalibrating themselves periodically. By default, if for 0.5
+		seconds there is no change in position, it's used as the new
+		zero. This duration is too low. Often, the calibration happens
+		when the trackpoint is in fact being used.

Documentation/admin-guide/README.rst

@@ -218,6 +218,13 @@ Configuring the kernel
      "make localyesconfig" Similar to localmodconfig, except it will convert
                            all module options to built in (=y) options.
 
+     "make kvmconfig"   Enable additional options for kvm guest kernel support.
+
+     "make xenconfig"   Enable additional options for xen dom0 guest kernel
+                        support.
+
+     "make tinyconfig"  Configure the tiniest possible kernel.
+
    You can find more information on using the Linux kernel config tools
    in Documentation/kbuild/kconfig.txt.
 

Documentation/admin-guide/module-signing.rst

@@ -180,11 +180,11 @@ Public keys in the kernel
 =========================
 
 The kernel contains a ring of public keys that can be viewed by root.  They're
-in a keyring called ".system_keyring" that can be seen by::
+in a keyring called ".builtin_trusted_keys" that can be seen by::
 
 	[root@deneb ~]# cat /proc/keys
 	...
-	223c7853 I------     1 perm 1f030000     0     0 keyring   .system_keyring: 1
+	223c7853 I------     1 perm 1f030000     0     0 keyring   .builtin_trusted_keys: 1
 	302d2d52 I------     1 perm 1f010000     0     0 asymmetri Fedora kernel signing key: d69a84e6bce3d216b979e9505b3e3ef9a7118079: X509.RSA a7118079 []
 	...
 
@@ -197,15 +197,15 @@ add those in also (e.g. from the UEFI key database).
 
 Finally, it is possible to add additional public keys by doing::
 
-	keyctl padd asymmetric "" [.system_keyring-ID] <[key-file]
+	keyctl padd asymmetric "" [.builtin_trusted_keys-ID] <[key-file]
 
 e.g.::
 
 	keyctl padd asymmetric "" 0x223c7853 <my_public_key.x509
 
 Note, however, that the kernel will only permit keys to be added to
-``.system_keyring _if_`` the new key's X.509 wrapper is validly signed by a key
-that is already resident in the .system_keyring at the time the key was added.
+``.builtin_trusted_keys`` **if** the new key's X.509 wrapper is validly signed by a key
+that is already resident in the ``.builtin_trusted_keys`` at the time the key was added.
 
 
 ========================

Documentation/admin-guide/security-bugs.rst

@@ -29,18 +29,20 @@ made public.
 Disclosure
 ----------
 
-The goal of the Linux kernel security team is to work with the
-bug submitter to bug resolution as well as disclosure.  We prefer
-to fully disclose the bug as soon as possible.  It is reasonable to
-delay disclosure when the bug or the fix is not yet fully understood,
-the solution is not well-tested or for vendor coordination.  However, we
-expect these delays to be short, measurable in days, not weeks or months.
-A disclosure date is negotiated by the security team working with the
-bug submitter as well as vendors.  However, the kernel security team
-holds the final say when setting a disclosure date.  The timeframe for
-disclosure is from immediate (esp. if it's already publicly known)
+The goal of the Linux kernel security team is to work with the bug
+submitter to understand and fix the bug.  We prefer to publish the fix as
+soon as possible, but try to avoid public discussion of the bug itself
+and leave that to others.
+
+Publishing the fix may be delayed when the bug or the fix is not yet
+fully understood, the solution is not well-tested or for vendor
+coordination.  However, we expect these delays to be short, measurable in
+days, not weeks or months.  A release date is negotiated by the security
+team working with the bug submitter as well as vendors.  However, the
+kernel security team holds the final say when setting a timeframe.  The
+timeframe varies from immediate (esp. if it's already publicly known bug)
 to a few weeks.  As a basic default policy, we expect report date to
-disclosure date to be on the order of 7 days.
+release date to be on the order of 7 days.
 
 Coordination
 ------------

Documentation/admin-guide/tainted-kernels.rst

@@ -6,7 +6,7 @@ counter. This indicates that the kernel has been tainted by some
 mechanism.  The string is followed by a series of position-sensitive
 characters, each representing a particular tainted value.
 
-  1) 'G' if all modules loaded have a GPL or compatible license, 'P' if
+ 1)  ``G`` if all modules loaded have a GPL or compatible license, ``P`` if
      any proprietary module has been loaded.  Modules without a
      MODULE_LICENSE or with a MODULE_LICENSE that is not recognised by
      insmod as GPL compatible are assumed to be proprietary.

Documentation/core-api/printk-formats.rst

@@ -60,8 +60,8 @@ Plain Pointers
 Pointers printed without a specifier extension (i.e unadorned %p) are
 hashed to prevent leaking information about the kernel memory layout. This
 has the added benefit of providing a unique identifier. On 64-bit machines
-the first 32 bits are zeroed. If you *really* want the address see %px
-below.
+the first 32 bits are zeroed. The kernel will print ``(ptrval)`` until it
+gathers enough entropy. If you *really* want the address see %px below.
 
 Symbols/Function Pointers
 -------------------------

Documentation/dev-tools/sparse.rst

@@ -67,7 +67,7 @@ __releases - The specified lock is held on function entry, but not exit.
 
 If the function enters and exits without the lock held, acquiring and
 releasing the lock inside the function in a balanced way, no
-annotation is needed.  The tree annotations above are for cases where
+annotation is needed.  The three annotations above are for cases where
 sparse would otherwise report a context imbalance.
 
 Getting sparse

Documentation/driver-api/dmaengine/dmatest.rst

@@ -6,10 +6,16 @@ Andy Shevchenko <andriy.shevchenko@linux.intel.com>
 
 This small document introduces how to test DMA drivers using dmatest module.
 
+.. note::
+  The test suite works only on the channels that have at least one
+  capability of the following: DMA_MEMCPY (memory-to-memory), DMA_MEMSET
+  (const-to-memory or memory-to-memory, when emulated), DMA_XOR, DMA_PQ.
+
 Part 1 - How to build the test module
 =====================================
 
 The menuconfig contains an option that could be found by following path:
+
 	Device Drivers -> DMA Engine support -> DMA Test client
 
 In the configuration file the option called CONFIG_DMATEST. The dmatest could
@@ -18,11 +24,11 @@ be built as module or inside kernel. Let's consider those cases.
 Part 2 - When dmatest is built as a module
 ==========================================
 
-Example of usage: ::
+Example of usage::
 
     % modprobe dmatest channel=dma0chan0 timeout=2000 iterations=1 run=1
 
-...or: ::
+...or::
 
     % modprobe dmatest
     % echo dma0chan0 > /sys/module/dmatest/parameters/channel
@@ -30,14 +36,12 @@ Example of usage: ::
     % echo 1 > /sys/module/dmatest/parameters/iterations
     % echo 1 > /sys/module/dmatest/parameters/run
 
-...or on the kernel command line: ::
+...or on the kernel command line::
 
     dmatest.channel=dma0chan0 dmatest.timeout=2000 dmatest.iterations=1 dmatest.run=1
 
-..hint:: available channel list could be extracted by running the following
-         command:
-
-::
+.. hint::
+  available channel list could be extracted by running the following command::
 
     % ls -1 /sys/class/dma/
 
@@ -59,12 +63,12 @@ before returning. For example, the following scripts wait for 42 tests
 to complete before exiting. Note that if 'iterations' is set to 'infinite' then
 waiting is disabled.
 
-Example: ::
+Example::
 
     % modprobe dmatest run=1 iterations=42 wait=1
     % modprobe -r dmatest
 
-...or: ::
+...or::
 
     % modprobe dmatest run=1 iterations=42
     % cat /sys/module/dmatest/parameters/wait
@@ -76,7 +80,7 @@ Part 3 - When built-in in the kernel
 The module parameters that is supplied to the kernel command line will be used
 for the first performed test. After user gets a control, the test could be
 re-run with the same or different parameters. For the details see the above
-section "Part 2 - When dmatest is built as a module..."
+section `Part 2 - When dmatest is built as a module`_.
 
 In both cases the module parameters are used as the actual values for the test
 case. You always could check them at run-time by running ::
@@ -86,22 +90,22 @@ case. You always could check them at run-time by running ::
 Part 4 - Gathering the test results
 ===================================
 
-Test results are printed to the kernel log buffer with the format: ::
+Test results are printed to the kernel log buffer with the format::
 
     "dmatest: result <channel>: <test id>: '<error msg>' with src_off=<val> dst_off=<val> len=<val> (<err code>)"
 
-Example of output: ::
-
+Example of output::
 
     % dmesg | tail -n 1
     dmatest: result dma0chan0-copy0: #1: No errors with src_off=0x7bf dst_off=0x8ad len=0x3fea (0)
 
-The message format is unified across the different types of errors. A number in
-the parens represents additional information, e.g. error code, error counter,
-or status. A test thread also emits a summary line at completion listing the
-number of tests executed, number that failed, and a result code.
+The message format is unified across the different types of errors. A
+number in the parentheses represents additional information, e.g. error
+code, error counter, or status. A test thread also emits a summary line at
+completion listing the number of tests executed, number that failed, and a
+result code.
 
-Example: ::
+Example::
 
     % dmesg | tail -n 1
     dmatest: dma0chan0-copy0: summary 1 test, 0 failures 1000 iops 100000 KB/s (0)

Documentation/driver-api/slimbus.rst

@@ -90,7 +90,7 @@ controller resets the bus. This notification allows the driver to take necessary
 steps to boot the device so that it's functional after the bus has been reset.
 
 Driver and Controller APIs:
---------------------------
+---------------------------
 .. kernel-doc:: include/linux/slimbus.h
    :internal:
 

Documentation/filesystems/xfs.txt

@@ -9,7 +9,7 @@ variable block sizes, is extent based, and makes extensive use of
 Btrees (directories, extents, free space) to aid both performance
 and scalability.
 
-Refer to the documentation at http://oss.sgi.com/projects/xfs/
+Refer to the documentation at https://xfs.wiki.kernel.org/
 for further details.  This implementation is on-disk compatible
 with the IRIX version of XFS.
 

Documentation/index.rst

@@ -64,6 +64,7 @@ merged much easier.
    dev-tools/index
    doc-guide/index
    kernel-hacking/index
+   trace/index
    maintainer/index
 
 Kernel API documentation

Documentation/infiniband/sysfs.txt

 SYSFS FILES
 
-  For each InfiniBand device, the InfiniBand drivers create the
-  following files under /sys/class/infiniband/<device name>:
-
-    node_type      - Node type (CA, switch or router)
-    node_guid      - Node GUID
-    sys_image_guid - System image GUID
-
-  In addition, there is a "ports" subdirectory, with one subdirectory
-  for each port.  For example, if mthca0 is a 2-port HCA, there will
-  be two directories:
-
-    /sys/class/infiniband/mthca0/ports/1
-    /sys/class/infiniband/mthca0/ports/2
-
-  (A switch will only have a single "0" subdirectory for switch port
-  0; no subdirectory is created for normal switch ports)
-
-  In each port subdirectory, the following files are created:
-
-    cap_mask       - Port capability mask
-    lid            - Port LID
-    lid_mask_count - Port LID mask count
-    rate           - Port data rate (active width * active speed)
-    sm_lid         - Subnet manager LID for port's subnet
-    sm_sl          - Subnet manager SL for port's subnet
-    state          - Port state (DOWN, INIT, ARMED, ACTIVE or ACTIVE_DEFER)
-    phys_state     - Port physical state (Sleep, Polling, LinkUp, etc)
-
-  There is also a "counters" subdirectory, with files
-
-    VL15_dropped
-    excessive_buffer_overrun_errors
-    link_downed
-    link_error_recovery
-    local_link_integrity_errors
-    port_rcv_constraint_errors
-    port_rcv_data
-    port_rcv_errors
-    port_rcv_packets
-    port_rcv_remote_physical_errors
-    port_rcv_switch_relay_errors
-    port_xmit_constraint_errors
-    port_xmit_data
-    port_xmit_discards
-    port_xmit_packets
-    symbol_error
-
-  Each of these files contains the corresponding value from the port's
-  Performance Management PortCounters attribute, as described in
-  section 16.1.3.5 of the InfiniBand Architecture Specification.
-
-  The "pkeys" and "gids" subdirectories contain one file for each
-  entry in the port's P_Key or GID table respectively.  For example,
-  ports/1/pkeys/10 contains the value at index 10 in port 1's P_Key
-  table.
-
-  There is an optional "hw_counters" subdirectory that may be under either
-  the parent device or the port subdirectories or both.  If present,
-  there are a list of counters provided by the hardware.  They may match
-  some of the counters in the counters directory, but they often include
-  many other counters.  In addition to the various counters, there will
-  be a file named "lifespan" that configures how frequently the core
-  should update the counters when they are being accessed (counters are
-  not updated if they are not being accessed).  The lifespan is in milli-
-  seconds and defaults to 10 unless set to something else by the driver.
-  Users may echo a value between 0 - 10000 to the lifespan file to set
-  the length of time between updates in milliseconds.
-
-MTHCA
-
-  The Mellanox HCA driver also creates the files:
-
-    hw_rev   - Hardware revision number
-    fw_ver   - Firmware version
-    hca_type - HCA type: "MT23108", "MT25208 (MT23108 compat mode)",
-               or "MT25208"
-
-HFI1
-
-  The hfi1 driver also creates these additional files:
-
-   hw_rev - hardware revision
-   board_id - manufacturing board id
-   tempsense - thermal sense information
-   serial - board serial number
-   nfreectxts - number of free user contexts
-   nctxts - number of allowed contexts (PSM2)
-   chip_reset - diagnostic (root only)
-   boardversion - board version
-
-   sdma<N>/ - one directory per sdma engine (0 - 15)
-	sdma<N>/cpu_list - read-write, list of cpus for user-process to sdma
-			   engine assignment.
-	sdma<N>/vl - read-only, vl the sdma engine maps to.
-
-	The new interface will give the user control on the affinity settings
-	for the hfi1 device.
-	As an example, to set an sdma engine irq affinity and thread affinity
-	of a user processes to use the sdma engine, which is "near" in terms
-	of NUMA configuration, or physical cpu location, the user will do:
-
-	echo "3" > /proc/irq/<N>/smp_affinity_list
-	echo "4-7" > /sys/devices/.../sdma3/cpu_list
-	cat /sys/devices/.../sdma3/vl
-	0
-	echo "8" > /proc/irq/<M>/smp_affinity_list
-	echo "9-12" > /sys/devices/.../sdma4/cpu_list
-	cat /sys/devices/.../sdma4/vl
-	1
-
-	to make sure that when a process runs on cpus 4,5,6, or 7,
-	and uses vl=0, then sdma engine 3 is selected by the driver,
-	and also the interrupt of the sdma engine 3 is steered to cpu 3.
-	Similarly, when a process runs on cpus 9,10,11, or 12 and sets vl=1,
-	then engine 4 will be selected and the irq of the sdma engine 4 is
-	steered to cpu 8.
-	This assumes that in the above N is the irq number of "sdma3",
-	and M is irq number of "sdma4" in the /proc/interrupts file.
-
-   ports/1/
-          CCMgtA/
-               cc_settings_bin - CCA tables used by PSM2
-               cc_table_bin
-               cc_prescan - enable prescaning for faster BECN response
-          sc2v/ - 32 files (0 - 31) used to translate sl->vl
-          sl2sc/ - 32 files (0 - 31) used to translate sl->sc
-          vl2mtu/ - 16 (0 - 15) files used to determine MTU for vl
+The sysfs interface has moved to
+Documentation/ABI/stable/sysfs-class-infiniband.

Documentation/input/devices/alps.rst

@@ -192,10 +192,13 @@ The final v3 packet type is the trackstick packet::
  byte 0:    1    1   x7   y7    1    1    1    1
  byte 1:    0   x6   x5   x4   x3   x2   x1   x0
  byte 2:    0   y6   y5   y4   y3   y2   y1   y0
- byte 3:    0    1    0    0    1    0    0    0
- byte 4:    0   z4   z3   z2   z1   z0    ?    ?
+ byte 3:    0    1   TP   SW    1    M    R    L
+ byte 4:    0   z6   z5   z4   z3   z2   z1   z0
  byte 5:    0    0    1    1    1    1    1    1
 
+TP means Tap SW status when tap processing is enabled or Press status when press
+processing is enabled. SW means scroll up when 4 buttons are available.
+
 ALPS Absolute Mode - Protocol Version 4
 ---------------------------------------
 

Documentation/process/5.Posting.rst

@@ -213,7 +213,7 @@ The tags in common use are:
    which can be found in Documentation/process/submitting-patches.rst.  Code without a
    proper signoff cannot be merged into the mainline.
 
- - Co-Developed-by: states that the patch was also created by another developer
+ - Co-developed-by: states that the patch was also created by another developer
    along with the original author.  This is useful at times when multiple
    people work on a single patch.  Note, this person also needs to have a
    Signed-off-by: line in the patch as well.

Documentation/process/changes.rst

@@ -430,7 +430,7 @@ udev
 FUSE
 ----
 
-- <http://sourceforge.net/projects/fuse>
+- <https://github.com/libfuse/libfuse/releases>
 
 mcelog
 ------

Documentation/process/coding-style.rst

@@ -200,6 +200,15 @@ statement; in the latter case use braces in both branches:
 		otherwise();
 	}
 
+Also, use braces when a loop contains more than a single simple statement:
+
+.. code-block:: c
+
+	while (condition) {
+		if (test)
+			do_something();
+	}
+
 3.1) Spaces
 ***********
 

Documentation/process/howto.rst

@@ -213,13 +213,6 @@ will learn the basics of getting your patch into the Linux kernel tree,
 and possibly be pointed in the direction of what to go work on next, if
 you do not already have an idea.
 
-If you already have a chunk of code that you want to put into the kernel
-tree, but need some help getting it in the proper form, the
-kernel-mentors project was created to help you out with this.  It is a
-mailing list, and can be found at:
-
-	https://selenic.com/mailman/listinfo/kernel-mentors
-
 Before making any actual modifications to the Linux kernel code, it is
 imperative to understand how the code in question works.  For this
 purpose, nothing is better than reading through it directly (most tricky
@@ -381,14 +374,6 @@ bugs is one of the best ways to get merits among other developers, because
 not many people like wasting time fixing other people's bugs.
 
 To work in the already reported bug reports, go to https://bugzilla.kernel.org.
-If you want to be advised of the future bug reports, you can subscribe to the
-bugme-new mailing list (only new bug reports are mailed here) or to the
-bugme-janitor mailing list (every change in the bugzilla is mailed here)
-
-	https://lists.linux-foundation.org/mailman/listinfo/bugme-new
-
-	https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
-
 
 
 Mailing lists

Documentation/process/kernel-driver-statement.rst

@@ -103,6 +103,7 @@ today, have in the past, or will in the future.
  - Auke Kok
  - Peter Korsgaard
  - Jiri Kosina
+ - Aaro Koskinen
  - Mariusz Kozlowski
  - Greg Kroah-Hartman
  - Michael Krufky

Documentation/process/license-rules.rst

@@ -4,15 +4,17 @@ Linux kernel licensing rules
 ============================
 
 The Linux Kernel is provided under the terms of the GNU General Public
-License version 2 only (GPL-2.0), as published by the Free Software
-Foundation, and provided in the COPYING file.  This documentation file is
-not meant to replace the COPYING file, but provides a description of how
-each source file should be annotated to make the licensing it is governed
-under clear and unambiguous.
-
-The license in the COPYING file applies to the kernel source as a whole,
-though individual source files can have a different license which is
-required to be compatible with the GPL-2.0::
+License version 2 only (GPL-2.0), as provided in LICENSES/preferred/GPL-2.0,
+with an explicit syscall exception described in
+LICENSES/exceptions/Linux-syscall-note, as described in the COPYING file.
+
+This documentation file provides a description of how each source file
+should be annotated to make its license clear and unambiguous.
+It doesn't replace the Kernel's license.
+
+The license described in the COPYING file applies to the kernel source
+as a whole, though individual source files can have a different license
+which is required to be compatible with the GPL-2.0::
 
     GPL-1.0+  :  GNU General Public License v1.0 or later
     GPL-2.0+  :  GNU General Public License v2.0 or later

Documentation/process/magic-number.rst

@@ -14,7 +14,7 @@ passing pointers to structures via a void * pointer.  The tty code,
 for example, does this frequently to pass driver-specific and line
 discipline-specific structures back and forth.
 
-The way to use magic numbers is to declare then at the beginning of
+The way to use magic numbers is to declare them at the beginning of
 the structure, like so::
 
 	struct tty_ldisc {

Documentation/process/submitting-patches.rst

@@ -510,8 +510,8 @@ tracking your trees, and to people trying to troubleshoot bugs in your
 tree.
 
 
-12) When to use Acked-by: and Cc:
----------------------------------
+12) When to use Acked-by:, Cc:, and Co-Developed-by:
+-------------------------------------------------------
 
 The Signed-off-by: tag indicates that the signer was involved in the
 development of the patch, or that he/she was in the patch's delivery path.
@@ -543,6 +543,11 @@ person it names - but it should indicate that this person was copied on the
 patch.  This tag documents that potentially interested parties
 have been included in the discussion.
 
+A Co-Developed-by: states that the patch was also created by another developer
+along with the original author.  This is useful at times when multiple people
+work on a single patch.  Note, this person also needs to have a Signed-off-by:
+line in the patch as well.
+
 
 13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
 --------------------------------------------------------------------------

Documentation/rapidio/sysfs.txt

-                         RapidIO sysfs Files
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-1. RapidIO Device Subdirectories
---------------------------------
-
-For each RapidIO device, the RapidIO subsystem creates files in an individual
-subdirectory with the following name, /sys/bus/rapidio/devices/<device_name>.
-
-The format of device_name is "nn:d:iiii", where:
-
-nn - two-digit hexadecimal ID of RapidIO network where the device resides
-d  - device typr: 'e' - for endpoint or 's' - for switch
-iiii - four-digit device destID for endpoints, or switchID for switches
-
-For example, below is a list of device directories that represents a typical
-RapidIO network with one switch, one host, and two agent endpoints, as it is
-seen by the enumerating host (destID = 1):
-
-/sys/bus/rapidio/devices/00:e:0000
-/sys/bus/rapidio/devices/00:e:0002
-/sys/bus/rapidio/devices/00:s:0001
-
-NOTE: An enumerating or discovering endpoint does not create a sysfs entry for
-itself, this is why an endpoint with destID=1 is not shown in the list.
-
-2. Attributes Common for All RapidIO Devices
---------------------------------------------
-
-Each device subdirectory contains the following informational read-only files:
-
-       did - returns the device identifier
-       vid - returns the device vendor identifier
-device_rev - returns the device revision level
-   asm_did - returns identifier for the assembly containing the device
-   asm_rev - returns revision level of the assembly containing the device
-   asm_vid - returns vendor identifier of the assembly containing the device
-   destid  - returns device destination ID assigned by the enumeration routine
-             (see 4.1 for switch specific details)
-   lprev   - returns name of previous device (switch) on the path to the device
-             that that owns this attribute
-  modalias - returns the device modalias
-
-In addition to the files listed above, each device has a binary attribute file
-that allows read/write access to the device configuration registers using
-the RapidIO maintenance transactions:
-
- config - reads from and writes to the device configuration registers.
-
-This attribute is similar in behavior to the "config" attribute of PCI devices
-and provides an access to the RapidIO device registers using standard file read
-and write operations.
-
-3. RapidIO Endpoint Device Attributes
--------------------------------------
-
-Currently Linux RapidIO subsystem does not create any endpoint specific sysfs
-attributes. It is possible that RapidIO master port drivers and endpoint device
-drivers will add their device-specific sysfs attributes but such attributes are
-outside the scope of this document.
-
-4. RapidIO Switch Device Attributes
------------------------------------
-
-RapidIO switches have additional attributes in sysfs. RapidIO subsystem supports
-common and device-specific sysfs attributes for switches. Because switches are
-integrated into the RapidIO subsystem, it offers a method to create
-device-specific sysfs attributes by specifying a callback function that may be
-set by the switch initialization routine during enumeration or discovery process.
-
-4.1 Common Switch Attributes
-
-   routes - reports switch routing information in "destID port" format. This
-            attribute reports only valid routing table entries, one line for
-            each entry.
-   destid - device destination ID that defines a route to the switch
- hopcount - number of hops on the path to the switch
-    lnext - returns names of devices linked to the switch except one of a device
-            linked to the ingress port (reported as "lprev"). This is an array
-            names with number of lines equal to number of ports in switch. If
-            a switch port has no attached device, returns "null" instead of
-            a device name.
-
-4.2 Device-specific Switch Attributes
-
-Device-specific switch attributes are listed for each RapidIO switch driver
-that exports additional attributes.
-
-IDT_GEN2:
- errlog - reads contents of device error log until it is empty.
-
-
-5. RapidIO Bus Attributes
--------------------------
-
-RapidIO bus subdirectory /sys/bus/rapidio implements the following bus-specific
-attribute:
-
-  scan - allows to trigger enumeration discovery process from user space. This
-	 is a write-only attribute. To initiate an enumeration or discovery
-	 process on specific mport device, a user needs to write mport_ID (not
-	 RapidIO destination ID) into this file. The mport_ID is a sequential
-	 number (0 ... RIO_MAX_MPORTS) assigned to the mport device.
-	 For example, for a machine with a single RapidIO controller, mport_ID
-	 for that controller always will be 0.
-	 To initiate RapidIO enumeration/discovery on all available mports
-	 a user must write '-1' (or RIO_MPORT_ANY) into this attribute file.
-
-
-6. RapidIO Bus Controllers/Ports
---------------------------------
-
-On-chip RapidIO controllers and PCIe-to-RapidIO bridges (referenced as
-"Master Port" or "mport") are presented in sysfs as the special class of
-devices: "rapidio_port".
-
-The /sys/class/rapidio_port subdirectory contains individual subdirectories
-named as "rapidioN" where N = mport ID registered with RapidIO subsystem.
-
-NOTE: An mport ID is not a RapidIO destination ID assigned to a given local
-mport device.
-
-Each mport device subdirectory in addition to standard entries contains the
-following device-specific attributes:
-
-   port_destid - reports RapidIO destination ID assigned to the given RapidIO
-                 mport device. If value 0xFFFFFFFF is returned this means that
-                 no valid destination ID have been assigned to the mport (yet).
-                 Normally, before enumeration/discovery have been executed only
-                 fabric enumerating mports have a valid destination ID assigned
-                 to them using "hdid=..." rapidio module parameter.
-      sys_size - reports RapidIO common transport system size:
-                   0 = small (8-bit destination ID, max. 256 devices),
-                   1 = large (16-bit destination ID, max. 65536 devices).
-
-After enumeration or discovery was performed for a given mport device,
-the corresponding subdirectory will also contain subdirectories for each
-child RapidIO device connected to the mport. Naming conventions for RapidIO
-devices are described in Section 1 above.
-
-The example below shows mport device subdirectory with several child RapidIO
-devices attached to it.
-
-[rio@rapidio ~]$ ls /sys/class/rapidio_port/rapidio0/ -l
-total 0
-drwxr-xr-x 3 root root    0 Feb 11 15:10 00:e:0001
-drwxr-xr-x 3 root root    0 Feb 11 15:10 00:e:0004
-drwxr-xr-x 3 root root    0 Feb 11 15:10 00:e:0007
-drwxr-xr-x 3 root root    0 Feb 11 15:10 00:s:0002
-drwxr-xr-x 3 root root    0 Feb 11 15:10 00:s:0003
-drwxr-xr-x 3 root root    0 Feb 11 15:10 00:s:0005
-lrwxrwxrwx 1 root root    0 Feb 11 15:11 device -> ../../../0000:01:00.0
--r--r--r-- 1 root root 4096 Feb 11 15:11 port_destid
-drwxr-xr-x 2 root root    0 Feb 11 15:11 power
-lrwxrwxrwx 1 root root    0 Feb 11 15:04 subsystem -> ../../../../../../class/rapidio_port
--r--r--r-- 1 root root 4096 Feb 11 15:11 sys_size
--rw-r--r-- 1 root root 4096 Feb 11 15:04 uevent
+The RapidIO sysfs files have moved to:
+Documentation/ABI/testing/sysfs-bus-rapidio and
+Documentation/ABI/testing/sysfs-class-rapidio

Documentation/trace/events-kmem.txt → Documentation/trace/events-kmem.rst

-			Subsystem Trace Points: kmem
+============================
+Subsystem Trace Points: kmem
+============================
 
 The kmem tracing system captures events related to object and page allocation
 within the kernel. Broadly speaking there are five major subheadings.
 
-  o Slab allocation of small objects of unknown type (kmalloc)
-  o Slab allocation of small objects of known type
-  o Page allocation
-  o Per-CPU Allocator Activity
-  o External Fragmentation
+  - Slab allocation of small objects of unknown type (kmalloc)
+  - Slab allocation of small objects of known type
+  - Page allocation
+  - Per-CPU Allocator Activity
+  - External Fragmentation
 
 This document describes what each of the tracepoints is and why they
 might be useful.
 
 1. Slab allocation of small objects of unknown type
 ===================================================
-kmalloc		call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s
-kmalloc_node	call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s node=%d
-kfree		call_site=%lx ptr=%p
+::
+
+  kmalloc		call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s
+  kmalloc_node	call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s node=%d
+  kfree		call_site=%lx ptr=%p
 
 Heavy activity for these events may indicate that a specific cache is
 justified, particularly if kmalloc slab pages are getting significantly
@@ -27,9 +31,11 @@ the allocation sites were.
 
 2. Slab allocation of small objects of known type
 =================================================
-kmem_cache_alloc	call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s
-kmem_cache_alloc_node	call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s node=%d
-kmem_cache_free		call_site=%lx ptr=%p
+::
+
+  kmem_cache_alloc	call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s
+  kmem_cache_alloc_node	call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s node=%d
+  kmem_cache_free		call_site=%lx ptr=%p
 
 These events are similar in usage to the kmalloc-related events except that
 it is likely easier to pin the event down to a specific cache. At the time
@@ -38,10 +44,12 @@ but the call_site can usually be used to extrapolate that information.
 
 3. Page allocation
 ==================
-mm_page_alloc		  page=%p pfn=%lu order=%d migratetype=%d gfp_flags=%s
-mm_page_alloc_zone_locked page=%p pfn=%lu order=%u migratetype=%d cpu=%d percpu_refill=%d
-mm_page_free		  page=%p pfn=%lu order=%d
-mm_page_free_batched	  page=%p pfn=%lu order=%d cold=%d
+::
+
+  mm_page_alloc		  page=%p pfn=%lu order=%d migratetype=%d gfp_flags=%s
+  mm_page_alloc_zone_locked page=%p pfn=%lu order=%u migratetype=%d cpu=%d percpu_refill=%d
+  mm_page_free		  page=%p pfn=%lu order=%d
+  mm_page_free_batched	  page=%p pfn=%lu order=%d cold=%d
 
 These four events deal with page allocation and freeing. mm_page_alloc is
 a simple indicator of page allocator activity. Pages may be allocated from
@@ -65,8 +73,10 @@ contention on the zone->lru_lock.
 
 4. Per-CPU Allocator Activity
 =============================
-mm_page_alloc_zone_locked	page=%p pfn=%lu order=%u migratetype=%d cpu=%d percpu_refill=%d
-mm_page_pcpu_drain		page=%p pfn=%lu order=%d cpu=%d migratetype=%d
+::
+
+  mm_page_alloc_zone_locked	page=%p pfn=%lu order=%u migratetype=%d cpu=%d percpu_refill=%d
+  mm_page_pcpu_drain		page=%p pfn=%lu order=%d cpu=%d migratetype=%d
 
 In front of the page allocator is a per-cpu page allocator. It exists only
 for order-0 pages, reduces contention on the zone->lock and reduces the
@@ -92,7 +102,9 @@ can be allocated and freed on the same CPU through some algorithm change.
 
 5. External Fragmentation
 =========================
-mm_page_alloc_extfrag		page=%p pfn=%lu alloc_order=%d fallback_order=%d pageblock_order=%d alloc_migratetype=%d fallback_migratetype=%d fragmenting=%d change_ownership=%d
+::
+
+  mm_page_alloc_extfrag		page=%p pfn=%lu alloc_order=%d fallback_order=%d pageblock_order=%d alloc_migratetype=%d fallback_migratetype=%d fragmenting=%d change_ownership=%d
 
 External fragmentation affects whether a high-order allocation will be
 successful or not. For some types of hardware, this is important although

Documentation/trace/events-msr.txt → Documentation/trace/events-msr.rst

+================
+MSR Trace Events
+================
 
 The x86 kernel supports tracing most MSR (Model Specific Register) accesses.
 To see the definition of the MSRs on Intel systems please see the SDM
@@ -7,31 +10,31 @@ Available trace points:
 
 /sys/kernel/debug/tracing/events/msr/
 
-Trace MSR reads
+Trace MSR reads:
 
 read_msr
 
-msr: MSR number
-val: Value written
-failed: 1 if the access failed, otherwise 0
+  - msr: MSR number
+  - val: Value written
+  - failed: 1 if the access failed, otherwise 0
 
 
-Trace MSR writes
+Trace MSR writes:
 
 write_msr
 
-msr: MSR number
-val: Value written
-failed: 1 if the access failed, otherwise 0
+  - msr: MSR number
+  - val: Value written
+  - failed: 1 if the access failed, otherwise 0
 
 
-Trace RDPMC in kernel
+Trace RDPMC in kernel:
 
 rdpmc
 
-The trace data can be post processed with the postprocess/decode_msr.py script
+The trace data can be post processed with the postprocess/decode_msr.py script::
 
-cat /sys/kernel/debug/tracing/trace | decode_msr.py /usr/src/linux/include/asm/msr-index.h
+  cat /sys/kernel/debug/tracing/trace | decode_msr.py /usr/src/linux/include/asm/msr-index.h
 
 to add symbolic MSR names.
 

Documentation/trace/events-nmi.txt → Documentation/trace/events-nmi.rst

+================
 NMI Trace Events
+================
 
 These events normally show up here:
 
 	/sys/kernel/debug/tracing/events/nmi
 
---
 
-nmi_handler:
+nmi_handler
+-----------
 
 You might want to use this tracepoint if you suspect that your
 NMI handlers are hogging large amounts of CPU time.  The kernel
-will warn if it sees long-running handlers:
+will warn if it sees long-running handlers::
 
 	INFO: NMI handler took too long to run: 9.207 msecs
 
@@ -19,7 +21,7 @@ more details.
 
 Let's say you suspect that perf_event_nmi_handler() is causing
 you some problems and you only want to trace that handler
-specifically.  You need to find its address:
+specifically.  You need to find its address::
 
 	$ grep perf_event_nmi_handler /proc/kallsyms
 	ffffffff81625600 t perf_event_nmi_handler
@@ -27,17 +29,17 @@ specifically.  You need to find its address:
 Let's also say you are only interested in when that function is
 really hogging a lot of CPU time, like a millisecond at a time.
 Note that the kernel's output is in milliseconds, but the input
-to the filter is in nanoseconds!  You can filter on 'delta_ns':
+to the filter is in nanoseconds!  You can filter on 'delta_ns'::
 
-cd /sys/kernel/debug/tracing/events/nmi/nmi_handler
-echo 'handler==0xffffffff81625600 && delta_ns>1000000' > filter
-echo 1 > enable
+	cd /sys/kernel/debug/tracing/events/nmi/nmi_handler
+	echo 'handler==0xffffffff81625600 && delta_ns>1000000' > filter
+	echo 1 > enable
 
-Your output would then look like:
+Your output would then look like::
 
-$ cat /sys/kernel/debug/tracing/trace_pipe
-<idle>-0     [000] d.h3   505.397558: nmi_handler: perf_event_nmi_handler() delta_ns: 3236765 handled: 1
-<idle>-0     [000] d.h3   505.805893: nmi_handler: perf_event_nmi_handler() delta_ns: 3174234 handled: 1
-<idle>-0     [000] d.h3   506.158206: nmi_handler: perf_event_nmi_handler() delta_ns: 3084642 handled: 1
-<idle>-0     [000] d.h3   506.334346: nmi_handler: perf_event_nmi_handler() delta_ns: 3080351 handled: 1
+	$ cat /sys/kernel/debug/tracing/trace_pipe
+	<idle>-0     [000] d.h3   505.397558: nmi_handler: perf_event_nmi_handler() delta_ns: 3236765 handled: 1
+	<idle>-0     [000] d.h3   505.805893: nmi_handler: perf_event_nmi_handler() delta_ns: 3174234 handled: 1
+	<idle>-0     [000] d.h3   506.158206: nmi_handler: perf_event_nmi_handler() delta_ns: 3084642 handled: 1
+	<idle>-0     [000] d.h3   506.334346: nmi_handler: perf_event_nmi_handler() delta_ns: 3080351 handled: 1
 

Documentation/trace/events-power.txt → Documentation/trace/events-power.rst

-
-			Subsystem Trace Points: power
+=============================
+Subsystem Trace Points: power
+=============================
 
 The power tracing system captures events related to power transitions
 within the kernel. Broadly speaking there are three major subheadings:
 
-  o Power state switch which reports events related to suspend (S-states),
+  - Power state switch which reports events related to suspend (S-states),
     cpuidle (C-states) and cpufreq (P-states)
-  o System clock related changes
-  o Power domains related changes and transitions
+  - System clock related changes
+  - Power domains related changes and transitions
 
 This document describes what each of the tracepoints is and why they
 might be useful.
@@ -22,14 +23,16 @@ Cf. include/trace/events/power.h for the events definitions.
 
 A 'cpu' event class gathers the CPU-related events: cpuidle and
 cpufreq.
+::
 
-cpu_idle		"state=%lu cpu_id=%lu"
-cpu_frequency		"state=%lu cpu_id=%lu"
+  cpu_idle		"state=%lu cpu_id=%lu"
+  cpu_frequency		"state=%lu cpu_id=%lu"
 
 A suspend event is used to indicate the system going in and out of the
 suspend mode:
+::
 
-machine_suspend		"state=%lu"
+  machine_suspend		"state=%lu"
 
 
 Note: the value of '-1' or '4294967295' for state means an exit from the current state,
@@ -45,10 +48,11 @@ correctly draw the states diagrams and to calculate accurate statistics etc.
 ================
 The clock events are used for clock enable/disable and for
 clock rate change.
+::
 
-clock_enable		"%s state=%lu cpu_id=%lu"
-clock_disable		"%s state=%lu cpu_id=%lu"
-clock_set_rate		"%s state=%lu cpu_id=%lu"
+  clock_enable		"%s state=%lu cpu_id=%lu"
+  clock_disable		"%s state=%lu cpu_id=%lu"
+  clock_set_rate		"%s state=%lu cpu_id=%lu"
 
 The first parameter gives the clock name (e.g. "gpio1_iclk").
 The second parameter is '1' for enable, '0' for disable, the target
@@ -57,8 +61,9 @@ clock rate for set_rate.
 3. Power domains events
 =======================
 The power domain events are used for power domains transitions
+::
 
-power_domain_target	"%s state=%lu cpu_id=%lu"
+  power_domain_target	"%s state=%lu cpu_id=%lu"
 
 The first parameter gives the power domain name (e.g. "mpu_pwrdm").
 The second parameter is the power domain target state.
@@ -67,28 +72,31 @@ The second parameter is the power domain target state.
 ================
 The PM QoS events are used for QoS add/update/remove request and for
 target/flags update.
+::
 
-pm_qos_add_request                 "pm_qos_class=%s value=%d"
-pm_qos_update_request              "pm_qos_class=%s value=%d"
-pm_qos_remove_request              "pm_qos_class=%s value=%d"
-pm_qos_update_request_timeout      "pm_qos_class=%s value=%d, timeout_us=%ld"
+  pm_qos_add_request                 "pm_qos_class=%s value=%d"
+  pm_qos_update_request              "pm_qos_class=%s value=%d"
+  pm_qos_remove_request              "pm_qos_class=%s value=%d"
+  pm_qos_update_request_timeout      "pm_qos_class=%s value=%d, timeout_us=%ld"
 
 The first parameter gives the QoS class name (e.g. "CPU_DMA_LATENCY").
 The second parameter is value to be added/updated/removed.
 The third parameter is timeout value in usec.
+::
 
-pm_qos_update_target               "action=%s prev_value=%d curr_value=%d"
-pm_qos_update_flags                "action=%s prev_value=0x%x curr_value=0x%x"
+  pm_qos_update_target               "action=%s prev_value=%d curr_value=%d"
+  pm_qos_update_flags                "action=%s prev_value=0x%x curr_value=0x%x"
 
 The first parameter gives the QoS action name (e.g. "ADD_REQ").
 The second parameter is the previous QoS value.
 The third parameter is the current QoS value to update.
 
 And, there are also events used for device PM QoS add/update/remove request.
+::
 
-dev_pm_qos_add_request             "device=%s type=%s new_value=%d"
-dev_pm_qos_update_request          "device=%s type=%s new_value=%d"
-dev_pm_qos_remove_request          "device=%s type=%s new_value=%d"
+  dev_pm_qos_add_request             "device=%s type=%s new_value=%d"
+  dev_pm_qos_update_request          "device=%s type=%s new_value=%d"
+  dev_pm_qos_remove_request          "device=%s type=%s new_value=%d"
 
 The first parameter gives the device name which tries to add/update/remove
 QoS requests.

Documentation/trace/ftrace-uses.rst

@@ -21,13 +21,14 @@ how to use ftrace to implement your own function callbacks.
 
 The ftrace context
 ==================
+.. warning::
 
-WARNING: The ability to add a callback to almost any function within the
-kernel comes with risks. A callback can be called from any context
-(normal, softirq, irq, and NMI). Callbacks can also be called just before
-going to idle, during CPU bring up and takedown, or going to user space.
-This requires extra care to what can be done inside a callback. A callback
-can be called outside the protective scope of RCU.
+  The ability to add a callback to almost any function within the
+  kernel comes with risks. A callback can be called from any context
+  (normal, softirq, irq, and NMI). Callbacks can also be called just before
+  going to idle, during CPU bring up and takedown, or going to user space.
+  This requires extra care to what can be done inside a callback. A callback
+  can be called outside the protective scope of RCU.
 
 The ftrace infrastructure has some protections agains recursions and RCU
 but one must still be very careful how they use the callbacks.
@@ -54,15 +55,15 @@ an ftrace_ops with ftrace:
 
 Both .flags and .private are optional. Only .func is required.
 
-To enable tracing call::
+To enable tracing call:
 
 .. c:function::  register_ftrace_function(&ops);
 
-To disable tracing call::
+To disable tracing call:
 
 .. c:function::  unregister_ftrace_function(&ops);
 
-The above is defined by including the header::
+The above is defined by including the header:
 
 .. c:function:: #include <linux/ftrace.h>
 
@@ -200,7 +201,7 @@ match a specific pattern.
 
 See Filter Commands in :file:`Documentation/trace/ftrace.txt`.
 
-To just trace the schedule function::
+To just trace the schedule function:
 
 .. code-block:: c
 
@@ -210,7 +211,7 @@ To add more functions, call the ftrace_set_filter() more than once with the
 @reset parameter set to zero. To remove the current filter set and replace it
 with new functions defined by @buf, have @reset be non-zero.
 
-To remove all the filtered functions and trace all functions::
+To remove all the filtered functions and trace all functions:
 
 .. code-block:: c
 

Documentation/trace/hwlat_detector.txt → Documentation/trace/hwlat_detector.rst

-Introduction:
+=========================
+Hardware Latency Detector
+=========================
+
+Introduction
 -------------
 
 The tracer hwlat_detector is a special purpose tracer that is used to
@@ -28,7 +32,7 @@ Note that the hwlat detector should *NEVER* be used in a production environment.
 It is intended to be run manually to determine if the hardware platform has a
 problem with long system firmware service routines.
 
-Usage:
+Usage
 ------
 
 Write the ASCII text "hwlat" into the current_tracer file of the tracing system
@@ -36,16 +40,16 @@ Write the ASCII text "hwlat" into the current_tracer file of the tracing system
 redefine the threshold in microseconds (us) above which latency spikes will
 be taken into account.
 
-Example:
+Example::
 
 	# echo hwlat > /sys/kernel/tracing/current_tracer
 	# echo 100 > /sys/kernel/tracing/tracing_thresh
 
 The /sys/kernel/tracing/hwlat_detector interface contains the following files:
 
-width			- time period to sample with CPUs held (usecs)
+  - width - time period to sample with CPUs held (usecs)
             must be less than the total window size (enforced)
-window			- total period of sampling, width being inside (usecs)
+  - window - total period of sampling, width being inside (usecs)
 
 By default the width is set to 500,000 and window to 1,000,000, meaning that
 for every 1,000,000 usecs (1s) the hwlat detector will spin for 500,000 usecs
@@ -67,11 +71,11 @@ The following tracing directory files are used by the hwlat_detector:
 
 in /sys/kernel/tracing:
 
- tracing_threshold	- minimum latency value to be considered (usecs)
- tracing_max_latency	- maximum hardware latency actually observed (usecs)
- tracing_cpumask	- the CPUs to move the hwlat thread across
- hwlat_detector/width	- specified amount of time to spin within window (usecs)
- hwlat_detector/window	- amount of time between (width) runs (usecs)
+ - tracing_threshold	- minimum latency value to be considered (usecs)
+ - tracing_max_latency	- maximum hardware latency actually observed (usecs)
+ - tracing_cpumask	- the CPUs to move the hwlat thread across
+ - hwlat_detector/width	- specified amount of time to spin within window (usecs)
+ - hwlat_detector/window	- amount of time between (width) runs (usecs)
 
 The hwlat detector's kernel thread will migrate across each CPU specified in
 tracing_cpumask between each window. To limit the migration, either modify

Documentation/trace/index.rst

+==========================
+Linux Tracing Technologies
+==========================
+
+.. toctree::
+   :maxdepth: 2
+
+   ftrace-design
+   tracepoint-analysis
+   ftrace
+   ftrace-uses
+   kprobetrace
+   uprobetracer
+   tracepoints
+   events
+   events-kmem
+   events-power
+   events-nmi
+   events-msr
+   mmiotrace
+   hwlat_detector
+   intel_th
+   stm

Documentation/trace/intel_th.txt → Documentation/trace/intel_th.rst

+=======================
 Intel(R) Trace Hub (TH)
 =======================
 
@@ -65,41 +66,41 @@ allocated, are accessible via /dev/intel_th0/msc{0,1}.
 Quick example
 -------------
 
-# figure out which GTH port is the first memory controller:
+# figure out which GTH port is the first memory controller::
 
-$ cat /sys/bus/intel_th/devices/0-msc0/port
-0
+	$ cat /sys/bus/intel_th/devices/0-msc0/port
+	0
 
-# looks like it's port 0, configure master 33 to send data to port 0:
+# looks like it's port 0, configure master 33 to send data to port 0::
 
-$ echo 0 > /sys/bus/intel_th/devices/0-gth/masters/33
+	$ echo 0 > /sys/bus/intel_th/devices/0-gth/masters/33
 
 # allocate a 2-windowed multiblock buffer on the first memory
-# controller, each with 64 pages:
+# controller, each with 64 pages::
 
-$ echo multi > /sys/bus/intel_th/devices/0-msc0/mode
-$ echo 64,64 > /sys/bus/intel_th/devices/0-msc0/nr_pages
+	$ echo multi > /sys/bus/intel_th/devices/0-msc0/mode
+	$ echo 64,64 > /sys/bus/intel_th/devices/0-msc0/nr_pages
 
-# enable wrapping for this controller, too:
+# enable wrapping for this controller, too::
 
-$ echo 1 > /sys/bus/intel_th/devices/0-msc0/wrap
+	$ echo 1 > /sys/bus/intel_th/devices/0-msc0/wrap
 
-# and enable tracing into this port:
+# and enable tracing into this port::
 
-$ echo 1 > /sys/bus/intel_th/devices/0-msc0/active
+	$ echo 1 > /sys/bus/intel_th/devices/0-msc0/active
 
 # .. send data to master 33, see stm.txt for more details ..
 # .. wait for traces to pile up ..
-# .. and stop the trace:
+# .. and stop the trace::
 
-$ echo 0 > /sys/bus/intel_th/devices/0-msc0/active
+	$ echo 0 > /sys/bus/intel_th/devices/0-msc0/active
 
-# and now you can collect the trace from the device node:
+# and now you can collect the trace from the device node::
 
-$ cat /dev/intel_th0/msc0 > my_stp_trace
+	$ cat /dev/intel_th0/msc0 > my_stp_trace
 
 Host Debugger Mode
-==================
+------------------
 
 It is possible to configure the Trace Hub and control its trace
 capture from a remote debug host, which should be connected via one of

Documentation/trace/stm.txt → Documentation/trace/stm.rst

+===================
 System Trace Module
 ===================
 
@@ -32,14 +33,14 @@ associated with it, located in "stp-policy" subsystem directory in
 configfs. The topmost directory's name (the policy) is formatted as
 the STM device name to which this policy applies and and arbitrary
 string identifier separated by a stop. From the examle above, a rule
-may look like this:
+may look like this::
 
-$ ls /config/stp-policy/dummy_stm.my-policy/user
-channels masters
-$ cat /config/stp-policy/dummy_stm.my-policy/user/masters
-48 63
-$ cat /config/stp-policy/dummy_stm.my-policy/user/channels
-0 127
+	$ ls /config/stp-policy/dummy_stm.my-policy/user
+	channels masters
+	$ cat /config/stp-policy/dummy_stm.my-policy/user/masters
+	48 63
+	$ cat /config/stp-policy/dummy_stm.my-policy/user/channels
+	0 127
 
 which means that the master allocation pool for this rule consists of
 masters 48 through 63 and channel allocation pool has channels 0
@@ -78,9 +79,9 @@ stm_source
 For kernel-based trace sources, there is "stm_source" device
 class. Devices of this class can be connected and disconnected to/from
 stm devices at runtime via a sysfs attribute called "stm_source_link"
-by writing the name of the desired stm device there, for example:
+by writing the name of the desired stm device there, for example::
 
-$ echo dummy_stm.0 > /sys/class/stm_source/console/stm_source_link
+	$ echo dummy_stm.0 > /sys/class/stm_source/console/stm_source_link
 
 For examples on how to use stm_source interface in the kernel, refer
 to stm_console, stm_heartbeat or stm_ftrace drivers.
@@ -118,5 +119,5 @@ the same time.
 
 Currently only Ftrace "function" tracer is supported.
 
-[1] https://software.intel.com/sites/default/files/managed/d3/3c/intel-th-developer-manual.pdf
-[2] http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0444b/index.html
+* [1] https://software.intel.com/sites/default/files/managed/d3/3c/intel-th-developer-manual.pdf
+* [2] http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0444b/index.html

README

 Linux kernel
 ============
 
-This file was moved to Documentation/admin-guide/README.rst
-
-Please notice that there are several guides for kernel developers and users.
-These guides can be rendered in a number of formats, like HTML and PDF.
+There are several guides for kernel developers and users. These guides can
+be rendered in a number of formats, like HTML and PDF. Please read
+Documentation/admin-guide/README.rst first.
 
 In order to build the documentation, use ``make htmldocs`` or
-``make pdfdocs``.
+``make pdfdocs``.  The formatted documentation can also be read online at:
+
+    https://www.kernel.org/doc/html/latest/
 
 There are various text files in the Documentation/ subdirectory,
 several of them using the Restructured Text markup notation.