Re: [PATCH v2 28/39] docs: ABI: fix syntax to be parsed using ReST notation

From: "Joseph, Jithu" <jithu.joseph@intel.com>
To: "mchehab+huawei@kernel.org" <mchehab+huawei@kernel.org>,
	"linux-doc@vger.kernel.org" <linux-doc@vger.kernel.org>
Cc: "jinpu.wang@cloud.ionos.com" <jinpu.wang@cloud.ionos.com>,
	"cw00.choi@samsung.com" <cw00.choi@samsung.com>,
	"gregkh@linuxfoundation.org" <gregkh@linuxfoundation.org>,
	"felix@linux.ibm.com" <felix@linux.ibm.com>,
	"lukasz.luba@arm.com" <lukasz.luba@arm.com>,
	"k.konieczny@samsung.com" <k.konieczny@samsung.com>,
	"jgg@ziepe.ca" <jgg@ziepe.ca>,
	"richard.gong@linux.intel.com" <richard.gong@linux.intel.com>,
	"dvhart@infradead.org" <dvhart@infradead.org>,
	"vadimp@nvidia.com" <vadimp@nvidia.com>,
	"ajd@linux.ibm.com" <ajd@linux.ibm.com>,
	"vaibhav@linux.ibm.com" <vaibhav@linux.ibm.com>,
	"danil.kipnis@cloud.ionos.com" <danil.kipnis@cloud.ionos.com>,
	"jolly.shah@xilinx.com" <jolly.shah@xilinx.com>,
	"christian.gromm@microchip.com" <christian.gromm@microchip.com>,
	"rajan.vaja@xilinx.com" <rajan.vaja@xilinx.com>,
	"michal.simek@xilinx.com" <michal.simek@xilinx.com>,
	"zbr@ioremap.net" <zbr@ioremap.net>, "Wu, Hao" <hao.wu@intel.com>,
	"Kang, Luwei" <luwei.kang@intel.com>,
	"Wysocki, Rafael J" <rafael.j.wysocki@intel.com>,
	"tejas.patel@xilinx.com" <tejas.patel@xilinx.com>,
	"ivan.zaentsev@wirenboard.ru" <ivan.zaentsev@wirenboard.ru>,
	"srinivas.pandruvada@linux.intel.com" 
	<srinivas.pandruvada@linux.intel.com>,
	"andy@infradead.org" <andy@infradead.org>,
	"gregory.clement@bootlin.com" <gregory.clement@bootlin.com>,
	"akira215corp@gmail.com" <akira215corp@gmail.com>,
	"fbarrat@linux.ibm.com" <fbarrat@linux.ibm.com>,
	"Xu, Yilun" <yilun.xu@intel.com>,
	"linux-arm-kernel@lists.infradead.org" 
	<linux-arm-kernel@lists.infradead.org>,
	"linux-pm@vger.kernel.org" <linux-pm@vger.kernel.org>,
	"Jonathan.Cameron@huawei.com" <Jonathan.Cameron@huawei.com>,
	"bvanassche@acm.org" <bvanassche@acm.org>,
	"marek.behun@nic.cz" <marek.behun@nic.cz>,
	"platform-driver-x86@vger.kernel.org" 
	<platform-driver-x86@vger.kernel.org>,
	"corbet@lwn.net" <corbet@lwn.net>,
	"b.zolnierkie@samsung.com" <b.zolnierkie@samsung.com>,
	"sre@kernel.org" <sre@kernel.org>,
	"linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>
Subject: Re: [PATCH v2 28/39] docs: ABI: fix syntax to be parsed using ReST notation
Date: Mon, 2 Nov 2020 18:39:21 +0000	[thread overview]
Message-ID: <61de64112cbe19f5f43cd02d4fd6e2f7447b3f61.camel@intel.com> (raw)
In-Reply-To: <55a89f423cf122982c462d257722e44d6ece4b36.1604042072.git.mchehab+huawei@kernel.org>

On Fri, 2020-10-30 at 08:40 +0100, Mauro Carvalho Chehab wrote:
> There are a number of new changes at the ABI files that cause
> them to produce warnings when generating ABI output.
> 
> Fix them.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  .../ABI/stable/sysfs-driver-firmware-zynqmp   | 62 ++++++++-----
>  Documentation/ABI/testing/debugfs-moxtet      | 28 ++++--
>  .../ABI/testing/debugfs-turris-mox-rwtm       |  6 +-
>  .../sysfs-bus-event_source-devices-dfl_fme    | 14 +--
>  Documentation/ABI/testing/sysfs-bus-most      |  6 +-
>  Documentation/ABI/testing/sysfs-class-devfreq |  6 +-
>  Documentation/ABI/testing/sysfs-class-ocxl    | 14 +--
>  .../ABI/testing/sysfs-class-power-wilco       | 18 ++--
>  .../ABI/testing/sysfs-class-rnbd-client       | 93 ++++++++++-------
> --
>  .../ABI/testing/sysfs-class-rtrs-client       | 23 +++--
>  .../sysfs-devices-platform-stratix10-rsu      | 10 ++
>  .../ABI/testing/sysfs-driver-w1_therm         | 75 ++++++++++-----
>  .../ABI/testing/sysfs-platform-dfl-fme        | 14 ++-
>  Documentation/ABI/testing/sysfs-platform-dptf | 11 ++-
>  .../sysfs-platform-intel-wmi-sbl-fw-update    |  1 +

For intel-wmi-sbl-fw-update part
Acked-by: Jithu Joseph<jithu.joseph@intel.com>

>  .../testing/sysfs-platform-mellanox-bootctl   | 50 ++++++----
>  .../ABI/testing/sysfs-platform-wilco-ec       |  1 +
>  17 files changed, 271 insertions(+), 161 deletions(-)
> 
> diff --git a/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
> b/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
> index 00fa04c76ff3..f5724bb5b462 100644
> --- a/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
> +++ b/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
> @@ -12,13 +12,15 @@ Description:
>  		resets. Three registers are used by the FSBL and
>  		other Xilinx software products:
> GLOBAL_GEN_STORAGE{4:6}.
>  
> -		Usage:
> -		# cat /sys/devices/platform/firmware\:zynqmp-
> firmware/ggs0
> -		# echo <value> >
> /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> +		Usage::
>  
> -		Example:
> -		# cat /sys/devices/platform/firmware\:zynqmp-
> firmware/ggs0
> -		# echo 0x1234ABCD >
> /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> +		    # cat /sys/devices/platform/firmware\:zynqmp-
> firmware/ggs0
> +		    # echo <value> >
> /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> +
> +		Example::
> +
> +		    # cat /sys/devices/platform/firmware\:zynqmp-
> firmware/ggs0
> +		    # echo 0x1234ABCD >
> /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
>  
>  Users:		Xilinx
>  
> @@ -39,13 +41,15 @@ Description:
>  		software products: PERS_GLOB_GEN_STORAGE{4:7}.
>  		Register is reset only by a POR reset.
>  
> -		Usage:
> -		# cat /sys/devices/platform/firmware\:zynqmp-
> firmware/pggs0
> -		# echo <value> >
> /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> +		Usage::
>  
> -		Example:
> -		# cat /sys/devices/platform/firmware\:zynqmp-
> firmware/pggs0
> -		# echo 0x1234ABCD >
> /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> +		    # cat /sys/devices/platform/firmware\:zynqmp-
> firmware/pggs0
> +		    # echo <value> >
> /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> +
> +		Example::
> +
> +		    # cat /sys/devices/platform/firmware\:zynqmp-
> firmware/pggs0
> +		    # echo 0x1234ABCD >
> /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
>  
>  Users:		Xilinx
>  
> @@ -61,23 +65,28 @@ Description:
>  
>  		Following are available shutdown scopes(subtypes):
>  
> -		subsystem:	Only the APU along with all of its
> peripherals
> +		subsystem:
> +				Only the APU along with all of its
> peripherals
>  				not used by other processing units will
> be
>  				shut down. This may result in the FPD
> power
>  				domain being shut down provided that no
> other
>  				processing unit uses FPD peripherals or
> DRAM.
> -		ps_only:	The complete PS will be shut down, including
> the
> +		ps_only:
> +				The complete PS will be shut down,
> including the
>  				RPU, PMU, etc.  Only the PL domain
> (FPGA)
>  				remains untouched.
> -		system:		The complete system/device is shut
> down.
> +		system:
> +				The complete system/device is shut
> down.
>  
> -		Usage:
> -		# cat /sys/devices/platform/firmware\:zynqmp-
> firmware/shutdown_scope
> -		# echo <scope> >
> /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> +		Usage::
>  
> -		Example:
> -		# cat /sys/devices/platform/firmware\:zynqmp-
> firmware/shutdown_scope
> -		# echo "subsystem" >
> /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> +		    # cat /sys/devices/platform/firmware\:zynqmp-
> firmware/shutdown_scope
> +		    # echo <scope> >
> /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> +
> +		Example::
> +
> +		    # cat /sys/devices/platform/firmware\:zynqmp-
> firmware/shutdown_scope
> +		    # echo "subsystem" >
> /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
>  
>  Users:		Xilinx
>  
> @@ -94,10 +103,13 @@ Description:
>  		system restart.
>  
>  		Usage:
> -		Set healthy bit
> -		# echo 1 > /sys/devices/platform/firmware\:zynqmp-
> firmware/health_status
>  
> -		Unset healthy bit
> -		# echo 0 > /sys/devices/platform/firmware\:zynqmp-
> firmware/health_status
> +		Set healthy bit::
> +
> +		    # echo 1 > /sys/devices/platform/firmware\:zynqmp-
> firmware/health_status
> +
> +		Unset healthy bit::
> +
> +		    # echo 0 > /sys/devices/platform/firmware\:zynqmp-
> firmware/health_status
>  
>  Users:		Xilinx
> diff --git a/Documentation/ABI/testing/debugfs-moxtet
> b/Documentation/ABI/testing/debugfs-moxtet
> index 67b1717794d8..15dfaecb2892 100644
> --- a/Documentation/ABI/testing/debugfs-moxtet
> +++ b/Documentation/ABI/testing/debugfs-moxtet
> @@ -5,10 +5,16 @@ Contact:	Marek Behún <marek.behun@nic.cz>
>  Description:	(R) Read input from the shift registers, in
> hexadecimal.
>  		Returns N+1 bytes, where N is the number of Moxtet
> connected
>  		modules. The first byte is from the CPU board itself.
> -		Example: 101214
> -			 10: CPU board with SD card
> -			 12: 2 = PCIe module, 1 = IRQ not active
> -			 14: 4 = Peridot module, 1 = IRQ not active
> +
> +		Example::
> +
> +			101214
> +
> +		==  =======================================
> +		10  CPU board with SD card
> +		12  2 = PCIe module, 1 = IRQ not active
> +		14  4 = Peridot module, 1 = IRQ not active
> +		==  =======================================
>  
>  What:		/sys/kernel/debug/moxtet/output
>  Date:		March 2019
> @@ -17,7 +23,13 @@ Contact:	Marek Behún <marek.behun@nic.cz>
>  Description:	(RW) Read last written value to the shift registers, in
>  		hexadecimal, or write values to the shift registers,
> also
>  		in hexadecimal.
> -		Example: 0102
> -			 01: 01 was last written, or is to be written,
> to the
> -			     first module's shift register
> -			 02: the same for second module
> +
> +		Example::
> +
> +		    0102
> +
> +		==  ================================================
> +		01  01 was last written, or is to be written, to the
> +		    first module's shift register
> +		02  the same for second module
> +		==  ================================================
> diff --git a/Documentation/ABI/testing/debugfs-turris-mox-rwtm
> b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
> index 2b3255ee68fd..c8f7dadd591c 100644
> --- a/Documentation/ABI/testing/debugfs-turris-mox-rwtm
> +++ b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
> @@ -2,8 +2,10 @@ What:		/sys/kernel/debug/turris-mox-
> rwtm/do_sign
>  Date:		Jun 2020
>  KernelVersion:	5.8
>  Contact:	Marek Behún <marek.behun@nic.cz>
> -Description:	(W) Message to sign with the ECDSA private key stored
> in
> +Description:	(W)
> +		    Message to sign with the ECDSA private key stored
> in
>  		    device's OTP. The message must be exactly 64 bytes
> (since
>  		    this is intended for SHA-512 hashes).
> -		(R) The resulting signature, 136 bytes. This contains
> the R and
> +		(R)
> +		    The resulting signature, 136 bytes. This contains
> the R and
>  		    S values of the ECDSA signature, both in big-endian 
> format.
> diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-
> devices-dfl_fme b/Documentation/ABI/testing/sysfs-bus-event_source-
> devices-dfl_fme
> index c9278a3b3df1..63a32ddcb95e 100644
> --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-
> dfl_fme
> +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-
> dfl_fme
> @@ -8,13 +8,13 @@ Description:	Read-only. Attribute group to
> describe the magic bits
>  
>  		Each attribute under this group defines a bit range of
> the
>  		perf_event_attr.config. All supported attributes are
> listed
> -		below.
> +		below::
>  
>  		    event  = "config:0-11"  - event ID
>  		    evtype = "config:12-15" - event type
>  		    portid = "config:16-23" - event source
>  
> -		For example,
> +		For example::
>  
>  		    fab_mmio_read =
> "event=0x06,evtype=0x02,portid=0xff"
>  
> @@ -40,11 +40,11 @@ Description:	Read-only. Attribute group to
> describe performance monitoring
>  
>  		All supported performance monitoring events are listed
> below.
>  
> -		Basic events (evtype=0x00)
> +		Basic events (evtype=0x00)::
>  
>  		    clock = "event=0x00,evtype=0x00,portid=0xff"
>  
> -		Cache events (evtype=0x01)
> +		Cache events (evtype=0x01)::
>  
>  		    cache_read_hit      =
> "event=0x00,evtype=0x01,portid=0xff"
>  		    cache_read_miss     =
> "event=0x01,evtype=0x01,portid=0xff"
> @@ -59,7 +59,7 @@ Description:	Read-only. Attribute group to
> describe performance monitoring
>  		    cache_rx_req_stall  =
> "event=0x09,evtype=0x01,portid=0xff"
>  		    cache_eviction      =
> "event=0x0a,evtype=0x01,portid=0xff"
>  
> -		Fabric events (evtype=0x02)
> +		Fabric events (evtype=0x02)::
>  
>  		    fab_pcie0_read       =
> "event=0x00,evtype=0x02,portid=0xff"
>  		    fab_pcie0_write      =
> "event=0x01,evtype=0x02,portid=0xff"
> @@ -78,7 +78,7 @@ Description:	Read-only. Attribute group to
> describe performance monitoring
>  		    fab_port_mmio_read   =
> "event=0x06,evtype=0x02,portid=?"
>  		    fab_port_mmio_write  =
> "event=0x07,evtype=0x02,portid=?"
>  
> -		VTD events (evtype=0x03)
> +		VTD events (evtype=0x03)::
>  
>  		    vtd_port_read_transaction  =
> "event=0x00,evtype=0x03,portid=?"
>  		    vtd_port_write_transaction =
> "event=0x01,evtype=0x03,portid=?"
> @@ -88,7 +88,7 @@ Description:	Read-only. Attribute group to
> describe performance monitoring
>  		    vtd_port_devtlb_2m_fill    =
> "event=0x05,evtype=0x03,portid=?"
>  		    vtd_port_devtlb_1g_fill    =
> "event=0x06,evtype=0x03,portid=?"
>  
> -		VTD SIP events (evtype=0x04)
> +		VTD SIP events (evtype=0x04)::
>  
>  		    vtd_sip_iotlb_4k_hit  =
> "event=0x00,evtype=0x04,portid=0xff"
>  		    vtd_sip_iotlb_2m_hit  =
> "event=0x01,evtype=0x04,portid=0xff"
> diff --git a/Documentation/ABI/testing/sysfs-bus-most
> b/Documentation/ABI/testing/sysfs-bus-most
> index ec0a603d804b..38cc03e408e7 100644
> --- a/Documentation/ABI/testing/sysfs-bus-most
> +++ b/Documentation/ABI/testing/sysfs-bus-most
> @@ -235,7 +235,8 @@ KernelVersion:	4.15
>  Contact:	Christian Gromm <christian.gromm@microchip.com>
>  Description:
>  		This is to read back the configured direction of the
> channel.
> -		The following strings will be accepted:
> +		The following strings will be accepted::
> +
>  			'tx',
>  			'rx'
>  Users:
> @@ -246,7 +247,8 @@ KernelVersion:	4.15
>  Contact:	Christian Gromm <christian.gromm@microchip.com>
>  Description:
>  		This is to read back the configured data type of the
> channel.
> -		The following strings will be accepted:
> +		The following strings will be accepted::
> +
>  			'control',
>  			'async',
>  			'sync',
> diff --git a/Documentation/ABI/testing/sysfs-class-devfreq
> b/Documentation/ABI/testing/sysfs-class-devfreq
> index 67af3f31e17c..386bc230a33d 100644
> --- a/Documentation/ABI/testing/sysfs-class-devfreq
> +++ b/Documentation/ABI/testing/sysfs-class-devfreq
> @@ -48,7 +48,8 @@ Description:
>  		driver should provide the list of available frequencies
>  		with its profile. If need to reset the statistics of
> devfreq
>  		behavior on a specific device, enter 0(zero) to
> 'trans_stat'
> -		as following:
> +		as following::
> +
>  			echo 0 > /sys/class/devfreq/.../trans_stat
>  
>  What:		/sys/class/devfreq/.../available_frequencies
> @@ -124,7 +125,8 @@ Description:
>  		This work timer is used by devfreq workqueue in order
> to
>  		monitor the device status such as utilization. The user
>  		can change the work timer on runtime according to their
> demand
> -		as following:
> +		as following::
> +
>  			echo deferrable > /sys/class/devfreq/.../timer
>  			echo delayed > /sys/class/devfreq/.../timer
>  
> diff --git a/Documentation/ABI/testing/sysfs-class-ocxl
> b/Documentation/ABI/testing/sysfs-class-ocxl
> index bf33f4fda58f..847a7edc3113 100644
> --- a/Documentation/ABI/testing/sysfs-class-ocxl
> +++ b/Documentation/ABI/testing/sysfs-class-ocxl
> @@ -13,8 +13,8 @@ Description:	read only
>  		where:
>  
>  			====	=====================================
> ==========
> -			n:	number of currently active contexts,
> for debug
> -			max:	maximum number of contexts supported
> by the AFU
> +			n	number of currently active contexts, for
> debug
> +			max	maximum number of contexts supported
> by the AFU
>  			====	=====================================
> ==========
>  
>  What:		/sys/class/ocxl/<afu name>/pp_mmio_size
> @@ -43,7 +43,9 @@ Contact:	linuxppc-dev@lists.ozlabs.org
>  Description:	read/write
>  		Control whether the FPGA is reloaded on a link reset.
> Enabled
>  		through a vendor-specific logic block on the FPGA.
> -			0	Do not reload FPGA image from flash
> -			1	Reload FPGA image from flash
> -			unavailable
> -				The device does not support this
> capability
> +
> +			===========  ==================================
> =========
> +			0	     Do not reload FPGA image from flash
> +			1	     Reload FPGA image from flash
> +			unavailable  The device does not support this
> capability
> +			===========  ==================================
> =========
> diff --git a/Documentation/ABI/testing/sysfs-class-power-wilco
> b/Documentation/ABI/testing/sysfs-class-power-wilco
> index 84fde1d0ada0..82af180fcaab 100644
> --- a/Documentation/ABI/testing/sysfs-class-power-wilco
> +++ b/Documentation/ABI/testing/sysfs-class-power-wilco
> @@ -4,17 +4,23 @@ KernelVersion:	5.2
>  Description:
>  		What charging algorithm to use:
>  
> -		Standard: Fully charges battery at a standard rate.
> -		Adaptive: Battery settings adaptively optimized based
> on
> +		Standard:
> +			Fully charges battery at a standard rate.
> +		Adaptive:
> +			Battery settings adaptively optimized based on
>  			typical battery usage pattern.
> -		Fast: Battery charges over a shorter period.
> -		Trickle: Extends battery lifespan, intended for users
> who
> +		Fast:
> +			Battery charges over a shorter period.
> +		Trickle:
> +			Extends battery lifespan, intended for users
> who
>  			primarily use their Chromebook while connected
> to AC.
> -		Custom: A low and high threshold percentage is
> specified.
> +		Custom:
> +			A low and high threshold percentage is
> specified.
>  			Charging begins when level drops below
>  			charge_control_start_threshold, and ceases when
>  			level is above charge_control_end_threshold.
> -		Long Life: Customized charge rate for last longer
> battery life.
> +		Long Life:
> +			Customized charge rate for last longer battery
> life.
>  			On Wilco device this mode is pre-configured in
> the factory
>  			through EC's private PID. Swiching to a
> different mode will
>  			be denied by Wilco EC when Long Life mode is
> enabled.
> diff --git a/Documentation/ABI/testing/sysfs-class-rnbd-client
> b/Documentation/ABI/testing/sysfs-class-rnbd-client
> index c084f203b41e..00c0286733d4 100644
> --- a/Documentation/ABI/testing/sysfs-class-rnbd-client
> +++ b/Documentation/ABI/testing/sysfs-class-rnbd-client
> @@ -5,62 +5,70 @@ Contact:	Jack Wang <jinpu.wang@cloud.ionos.com>
> Danil Kipnis <danil.kipnis@cloud
>  Description:	Provide information about RNBD-client.
>  		All sysfs files that are not read-only provide the
> usage information on read:
>  
> -		Example:
> -		# cat /sys/class/rnbd-client/ctl/map_device
> +		Example::
>  
> -		> Usage: echo "sessname=<name of the rtrs session>
> path=<[srcaddr,]dstaddr>
> -		> [path=<[srcaddr,]dstaddr>] device_path=<full path on
> remote side>
> -		> [access_mode=<ro|rw|migration>] > map_device
> -		>
> -		> addr ::= [ ip:<ipv4> | ip:<ipv6> | gid:<gid> ]
> +		    # cat /sys/class/rnbd-client/ctl/map_device
> +
> +		    > Usage: echo "sessname=<name of the rtrs session>
> path=<[srcaddr,]dstaddr>
> +		    > [path=<[srcaddr,]dstaddr>] device_path=<full path
> on remote side>
> +		    > [access_mode=<ro|rw|migration>] > map_device
> +		    >
> +		    > addr ::= [ ip:<ipv4> | ip:<ipv6> | gid:<gid> ]
>  
>  What:		/sys/class/rnbd-client/ctl/map_device
>  Date:		Feb 2020
>  KernelVersion:	5.7
>  Contact:	Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <
> danil.kipnis@cloud.ionos.com>
> -Description:	Expected format is the following:
> +Description:	Expected format is the following::
>  
> -		sessname=<name of the rtrs session>
> -		path=<[srcaddr,]dstaddr> [path=<[srcaddr,]dstaddr> ...]
> -		device_path=<full path on remote side>
> -		[access_mode=<ro|rw|migration>]
> +		    sessname=<name of the rtrs session>
> +		    path=<[srcaddr,]dstaddr> [path=<[srcaddr,]dstaddr>
> ...]
> +		    device_path=<full path on remote side>
> +		    [access_mode=<ro|rw|migration>]
>  
>  		Where:
>  
> -		sessname: accepts a string not bigger than 256 chars,
> which identifies
> -		a given session on the client and on the server.
> -		I.e. "clt_hostname-srv_hostname" could be a natural
> choice.
> +		sessname:
> +		    accepts a string not bigger than 256 chars, which
> identifies
> +		    a given session on the client and on the server.
> +		    I.e. "clt_hostname-srv_hostname" could be a natural
> choice.
>  
> -		path:     describes a connection between the client and
> the server by
> -		specifying destination and, when required, the source
> address.
> -		The addresses are to be provided in the following
> format:
> +		path:
> +		    describes a connection between the client and the
> server by
> +		    specifying destination and, when required, the
> source address.
> +		    The addresses are to be provided in the following
> format::
>  
> -		ip:<IPv6>
> -		ip:<IPv4>
> -		gid:<GID>
> +			ip:<IPv6>
> +			ip:<IPv4>
> +			gid:<GID>
>  
> -		for example:
> +		for example::
> +
> +		    path=ip:10.0.0.66
>  
> -		path=ip:10.0.0.66
>  		The single addr is treated as the destination.
>  		The connection will be established to this server from
> any client IP address.
>  
> -		path=ip:10.0.0.66,ip:10.0.1.66
> +		::
> +
> +		    path=ip:10.0.0.66,ip:10.0.1.66
> +
>  		First addr is the source address and the second is the
> destination.
>  
>  		If multiple "path=" options are specified multiple
> connection
>  		will be established and data will be sent according to
>  		the selected multipath policy (see RTRS mp_policy sysfs
> entry description).
>  
> -		device_path: Path to the block device on the server
> side. Path is specified
> -		relative to the directory on server side configured in
> the
> -		'dev_search_path' module parameter of the rnbd_server.
> -		The rnbd_server prepends the <device_path> received
> from client
> -		with <dev_search_path> and tries to open the
> -		<dev_search_path>/<device_path> block device.  On
> success,
> -		a /dev/rnbd<N> device file, a
> /sys/block/rnbd_client/rnbd<N>/
> -		directory and an entry in /sys/class/rnbd-
> client/ctl/devices
> -		will be created.
> +		device_path:
> +		    Path to the block device on the server side. Path
> is specified
> +		    relative to the directory on server side configured
> in the
> +		    'dev_search_path' module parameter of the
> rnbd_server.
> +		    The rnbd_server prepends the <device_path> received
> from client
> +		    with <dev_search_path> and tries to open the
> +		    <dev_search_path>/<device_path> block device.  On
> success,
> +		    a /dev/rnbd<N> device file, a
> /sys/block/rnbd_client/rnbd<N>/
> +		    directory and an entry in /sys/class/rnbd-
> client/ctl/devices
> +		    will be created.
>  
>  		If 'dev_search_path' contains '%SESSNAME%', then each
> session can
>  		have different devices namespace, e.g. server was
> configured with
> @@ -68,11 +76,12 @@ Description:	Expected format is the
> following:
>  		client has this string "sessname=blya device_path=sda",
> then server
>  		will try to open: /run/rnbd-devs/blya/sda.
>  
> -		access_mode: the access_mode parameter specifies if the
> device is to be
> -		mapped as "ro" read-only or "rw" read-write. The server
> allows
> -		a device to be exported in rw mode only once. The
> "migration"
> -		access mode has to be specified if a second mapping in
> read-write
> -		mode is desired.
> +		access_mode:
> +		    the access_mode parameter specifies if the device
> is to be
> +		    mapped as "ro" read-only or "rw" read-write. The
> server allows
> +		    a device to be exported in rw mode only once. The
> "migration"
> +		    access mode has to be specified if a second mapping
> in read-write
> +		    mode is desired.
>  
>  		By default "rw" is used.
>  
> @@ -91,7 +100,7 @@ Description:	Expected format is the
> following:
>  		is the same as the device name.  By extracting the last
> part of the
>  		path the path to the device /dev/<dev-name> can be
> build.
>  
> -		o /dev/block/$(cat /sys/class/rnbd-
> client/ctl/devices/<device_id>/dev)
> +		* /dev/block/$(cat /sys/class/rnbd-
> client/ctl/devices/<device_id>/dev)
>  
>  		How to find the <device_id> of the device is described
> on the next
>  		section.
> @@ -106,6 +115,6 @@ Description:	For each device mapped on the
> client a new symbolic link is created
>  		The <device_id> of each device is created as follows:
>  
>  		- If the 'device_path' provided during mapping contains
> slashes ("/"),
> -		they are replaced by exclamation mark ("!") and used as
> as the
> -		<device_id>. Otherwise, the <device_id> will be the
> same as the
> -		"device_path" provided.
> +		  they are replaced by exclamation mark ("!") and used
> as as the
> +		  <device_id>. Otherwise, the <device_id> will be the
> same as the
> +		  "device_path" provided.
> diff --git a/Documentation/ABI/testing/sysfs-class-rtrs-client
> b/Documentation/ABI/testing/sysfs-class-rtrs-client
> index e7e718db8941..0f7165aab251 100644
> --- a/Documentation/ABI/testing/sysfs-class-rtrs-client
> +++ b/Documentation/ABI/testing/sysfs-class-rtrs-client
> @@ -10,10 +10,10 @@ Date:		Feb 2020
>  KernelVersion:	5.7
>  Contact:	Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <
> danil.kipnis@cloud.ionos.com>
>  Description:	RW, adds a new path (connection) to an existing
> session. Expected format is the
> -		following:
> +		following::
>  
> -		<[source addr,]destination addr>
> -		*addr ::= [ ip:<ipv4|ipv6> | gid:<gid> ]
> +		    <[source addr,]destination addr>
> +		    *addr ::= [ ip:<ipv4|ipv6> | gid:<gid> ]
>  
>  What:		/sys/class/rtrs-client/<session-
> name>/max_reconnect_attempts
>  Date:		Feb 2020
> @@ -29,10 +29,10 @@ Contact:	Jack Wang <jinpu.wang@cloud.ionos.com>
> Danil Kipnis <danil.kipnis@cloud
>  Description:	Multipath policy specifies which path should be
> selected on each IO:
>  
>  		round-robin (0):
> -		select path in per CPU round-robin manner.
> +		    select path in per CPU round-robin manner.
>  
>  		min-inflight (1):
> -		select path with minimum inflights.
> +		    select path with minimum inflights.
>  
>  What:		/sys/class/rtrs-client/<session-name>/paths/
>  Date:		Feb 2020
> @@ -109,8 +109,11 @@ Description:	RTRS expects that each HCA IRQ
> is pinned to a separate CPU. If it's
>  		not the case, the processing of an I/O response could
> be processed on a
>  		different CPU than where it was originally
> submitted.  This file shows
>  		how many interrupts where generated on a non expected
> CPU.
> -		"from:" is the CPU on which the IRQ was expected, but
> not generated.
> -		"to:" is the CPU on which the IRQ was generated, but
> not expected.
> +
> +		"from:"
> +		    is the CPU on which the IRQ was expected, but not
> generated.
> +		"to:"
> +		    is the CPU on which the IRQ was generated, but not
> expected.
>  
>  What:		/sys/class/rtrs-client/<session-name>/paths/<
> src@dst>/stats/reconnects
>  Date:		Feb 2020
> @@ -125,7 +128,7 @@ Date:		Feb 2020
>  KernelVersion:	5.7
>  Contact:	Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <
> danil.kipnis@cloud.ionos.com>
>  Description:	Contains statistics regarding rdma operations and
> inflight operations.
> -		The output consists of 6 values:
> +		The output consists of 6 values::
>  
> -		<read-count> <read-total-size> <write-count> <write-
> total-size> \
> -		<inflights> <failovered>
> +		    <read-count> <read-total-size> <write-count> \
> +		    <write-total-size> <inflights> <failovered>
> diff --git a/Documentation/ABI/testing/sysfs-devices-platform-
> stratix10-rsu b/Documentation/ABI/testing/sysfs-devices-platform-
> stratix10-rsu
> index a8daceb4a956..ee253b033280 100644
> --- a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
> +++ b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
> @@ -102,6 +102,8 @@ Description:
>  		b[15:0]
>  			inform firmware the current software execution
>  			stage.
> +
> +			==	=====================================
> ======
>  			0	the first stage bootloader didn't run or
>  				didn't reach the point of launching
> second
>  				stage bootloader.
> @@ -111,21 +113,29 @@ Description:
>  			2	both first and second stage bootloader ran
>  				and the operating system launch was
>  				attempted.
> +			==	=====================================
> ======
>  
>  		b[16]
> +			==	=====================================
> ======
>  			1	firmware to reset current image retry
>  				counter.
>  			0	no action.
> +			==	=====================================
> ======
>  
>  		b[17]
> +			==	=====================================
> ======
>  			1	firmware to clear RSU log
>  			0	no action.
> +			==	=====================================
> ======
>  
>  		b[18]
>  			this is negative logic
> +
> +			==	=====================================
> ======
>  			1	no action
>  			0	firmware record the notify code defined
>  				in b[15:0].
> +			==	=====================================
> ======
>  
>  What:		/sys/devices/platform/stratix10-rsu.0/dcmf0
>  Date:		June 2020
> diff --git a/Documentation/ABI/testing/sysfs-driver-w1_therm
> b/Documentation/ABI/testing/sysfs-driver-w1_therm
> index 8873bbb075cb..6a37dc33ffdb 100644
> --- a/Documentation/ABI/testing/sysfs-driver-w1_therm
> +++ b/Documentation/ABI/testing/sysfs-driver-w1_therm
> @@ -22,8 +22,10 @@ Description:
>  		device data to its embedded EEPROM, either restore data
>  		embedded in device EEPROM. Be aware that devices
> support
>  		limited EEPROM writing cycles (typical 50k)
> +
>  			* 'save': save device RAM to EEPROM
>  			* 'restore': restore EEPROM data in device RAM
> +
>  Users:		any user space application which wants to
> communicate with
>  		w1_term device
>  
> @@ -33,9 +35,11 @@ Date:		May 2020
>  Contact:	Akira Shimahara <akira215corp@gmail.com>
>  Description:
>  		(RO) return the power status by asking the device
> +
>  			* '0': device parasite powered
>  			* '1': device externally powered
>  			* '-xx': xx is kernel error when reading power
> status
> +
>  Users:		any user space application which wants to
> communicate with
>  		w1_term device
>  
> @@ -49,10 +53,12 @@ Description:
>  		will be changed only in device RAM, so it will be
> cleared when
>  		power is lost. Trigger a 'save' to EEPROM command to
> keep
>  		values after power-on. Read or write are :
> +
>  			* '9..14': device resolution in bit
> -			or resolution to set in bit
> +			  or resolution to set in bit
>  			* '-xx': xx is kernel error when reading the
> resolution
>  			* Anything else: do nothing
> +
>  		Some DS18B20 clones are fixed in 12-bit resolution, so
> the
>  		actual resolution is read back from the chip and
> verified. Error
>  		is reported if the results differ.
> @@ -65,16 +71,18 @@ Date:		May 2020
>  Contact:	Akira Shimahara <akira215corp@gmail.com>
>  Description:
>  		(RO) return the temperature in 1/1000 degC.
> +
>  			* If a bulk read has been triggered, it will
> directly
> -			return the temperature computed when the bulk
> read
> -			occurred, if available. If not yet available,
> nothing
> -			is returned (a debug kernel message is sent),
> you
> -			should retry later on.
> +			  return the temperature computed when the bulk
> read
> +			  occurred, if available. If not yet available,
> nothing
> +			  is returned (a debug kernel message is sent),
> you
> +			  should retry later on.
>  			* If no bulk read has been triggered, it will
> trigger
> -			a conversion and send the result. Note that the
> -			conversion duration depend on the resolution
> (if
> -			device support this feature). It takes 94ms in
> 9bits
> -			resolution, 750ms for 12bits.
> +			  a conversion and send the result. Note that
> the
> +			  conversion duration depend on the resolution
> (if
> +			  device support this feature). It takes 94ms
> in 9bits
> +			  resolution, 750ms for 12bits.
> +
>  Users:		any user space application which wants to
> communicate with
>  		w1_term device
>  
> @@ -86,12 +94,14 @@ Description:
>  		(RW) return the temperature in 1/1000 degC.
>  		*read*: return 2 lines with the hexa output data sent
> on the
>  		bus, return the CRC check and temperature in 1/1000
> degC
> -		*write* :
> +		*write*:
> +
>  			* '0' : save the 2 or 3 bytes to the device
> EEPROM
> -			(i.e. TH, TL and config register)
> +			  (i.e. TH, TL and config register)
>  			* '9..14' : set the device resolution in RAM
> -			(if supported)
> +			  (if supported)
>  			* Anything else: do nothing
> +
>  		refer to Documentation/w1/slaves/w1_therm.rst for
> detailed
>  		information.
>  Users:		any user space application which wants to
> communicate with
> @@ -103,14 +113,21 @@ Date:		May 2020
>  Contact:	Akira Shimahara <akira215corp@gmail.com>
>  Description:
>  		(RW) trigger a bulk read conversion. read the status
> +
>  		*read*:
> -			* '-1': conversion in progress on at least 1
> sensor
> -			* '1' :	conversion complete but at least one
> sensor
> +			* '-1':
> +				conversion in progress on at least 1
> sensor
> +			* '1' :
> +				conversion complete but at least one
> sensor
>  				value has not been read yet
> -			* '0' :	no bulk operation. Reading
> temperature will
> +			* '0' :
> +				no bulk operation. Reading temperature
> will
>  				trigger a conversion on each device
> -		*write*: 'trigger': trigger a bulk read on all
> supporting
> +
> +		*write*:
> +			'trigger': trigger a bulk read on all
> supporting
>  			devices on the bus
> +
>  		Note that if a bulk read is sent but one sensor is not
> read
>  		immediately, the next access to temperature on this
> device
>  		will return the temperature measured at the time of
> issue
> @@ -128,14 +145,19 @@ Description:
>  		reset to default (datasheet) conversion time for a new
>  		resolution.
>  
> -		*read*: Actual conversion time in milliseconds.
> *write*:
> -			'0': Set the default conversion time from the
> datasheet.
> -			'1': Measure and set the conversion time. Make
> a single
> +		*read*:
> +			Actual conversion time in milliseconds.
> +
> +		*write*:
> +			* '0':
> +			     Set the default conversion time from the
> datasheet.
> +			* '1':
> +			     Measure and set the conversion time. Make
> a single
>  			     temperature conversion, measure an actual
> value.
>  			     Increase it by 20% for temperature range.
> A new
>  			     conversion time can be obtained by reading
> this
>  			     same attribute.
> -			other positive value:
> +			* other positive value:
>  			     Set the conversion time in milliseconds.
>  
>  Users:		An application using the w1_term device
> @@ -148,16 +170,21 @@ Description:
>  		(RW) Control optional driver settings.
>  		Bit masks to read/write (bitwise OR):
>  
> -                1: Enable check for conversion success. If byte 6 of
> +		==
> ============================================================
> +                 1 Enable check for conversion success. If byte 6 of
>                     scratchpad memory is 0xC after conversion, and
>                     temperature reads 85.00 (powerup value) or 127.94
>                     (insufficient power) - return a conversion error.
>  
> -                2: Enable poll for conversion completion. Generate
> read cycles
> +                2  Enable poll for conversion completion. Generate
> read cycles
>                     after the conversion start and wait for 1's. In
> parasite
>                     power mode this feature is not available.
> +		==
> ============================================================
>  
> -		*read*:  Currently selected features.
> -		*write*: Select features.
> +		*read*:
> +		    Currently selected features.
> +
> +		*write*:
> +		    Select features.
>  
>  Users:		An application using the w1_term device
> diff --git a/Documentation/ABI/testing/sysfs-platform-dfl-fme
> b/Documentation/ABI/testing/sysfs-platform-dfl-fme
> index 3683cb1cdc3d..d6ab34e81b9b 100644
> --- a/Documentation/ABI/testing/sysfs-platform-dfl-fme
> +++ b/Documentation/ABI/testing/sysfs-platform-dfl-fme
> @@ -113,8 +113,11 @@ KernelVersion:	5.5
>  Contact:	Wu Hao <hao.wu@intel.com>
>  Description:	Read-Only. Read this file to get the name of hwmon
> device, it
>  		supports values:
> -		    'dfl_fme_thermal' - thermal hwmon device name
> -		    'dfl_fme_power'   - power hwmon device name
> +
> +		=================  =========================
> +		'dfl_fme_thermal'  thermal hwmon device name
> +		'dfl_fme_power'    power hwmon device name
> +		=================  =========================
>  
>  What:		/sys/bus/platform/devices/dfl-
> fme.0/hwmon/hwmonX/temp1_input
>  Date:		October 2019
> @@ -169,8 +172,11 @@ KernelVersion:	5.5
>  Contact:	Wu Hao <hao.wu@intel.com>
>  Description:	Read-Only. Read this file to get the policy of hardware
> threshold1
>  		(see 'temp1_max'). It only supports two values
> (policies):
> -		    0 - AP2 state (90% throttling)
> -		    1 - AP1 state (50% throttling)
> +
> +		==  ==========================
> +		 0  AP2 state (90% throttling)
> +	         1  AP1 state (50% throttling)
> +		==  ==========================
>  
>  What:		/sys/bus/platform/devices/dfl-
> fme.0/hwmon/hwmonX/power1_input
>  Date:		October 2019
> diff --git a/Documentation/ABI/testing/sysfs-platform-dptf
> b/Documentation/ABI/testing/sysfs-platform-dptf
> index 2cbc660d163b..141834342a4d 100644
> --- a/Documentation/ABI/testing/sysfs-platform-dptf
> +++ b/Documentation/ABI/testing/sysfs-platform-dptf
> @@ -27,12 +27,15 @@ KernelVersion:	v4.10
>  Contact:	linux-acpi@vger.kernel.org
>  Description:
>  		(RO) Display the platform power source
> +
> +		========= ============================
>  		bits[3:0] Current power source
> -			0x00 = DC
> -			0x01 = AC
> -			0x02 = USB
> -			0x03 = Wireless Charger
> +			  - 0x00 = DC
> +			  - 0x01 = AC
> +			  - 0x02 = USB
> +			  - 0x03 = Wireless Charger
>  		bits[7:4] Power source sequence number
> +		========= ============================
>  
>  What:		/sys/bus/platform/devices/INT3407:00/dptf_power
> /battery_steady_power
>  Date:		Jul, 2016
> diff --git a/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-
> fw-update b/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-
> fw-update
> index 5aa618987cad..02ae1e9bbfc8 100644
> --- a/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-
> update
> +++ b/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-
> update
> @@ -8,5 +8,6 @@ Description:
>  		of 0 and userspace can signal SBL to update firmware,
>  		on next reboot, by writing a value of 1.
>  		There are two available states:
> +
>  		    * 0 -> Skip firmware update while rebooting
>  		    * 1 -> Attempt firmware update on next reboot
> diff --git a/Documentation/ABI/testing/sysfs-platform-mellanox-
> bootctl b/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
> index 401d202f478b..e79ca22e2f45 100644
> --- a/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
> +++ b/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
> @@ -5,10 +5,13 @@ Contact:	"Liming Sun <lsun@mellanox.com>"
>  Description:
>  		The Life-cycle state of the SoC, which could be one of
> the
>  		following values.
> -		  Production - Production state and can be updated to
> secure
> -		  GA Secured - Secure chip and not able to change state
> -		  GA Non-Secured - Non-Secure chip and not able to
> change state
> -		  RMA - Return Merchandise Authorization
> +
> +		==============  =======================================
> ======
> +		Production      Production state and can be updated to
> secure
> +		GA Secured      Secure chip and not able to change
> state
> +		GA Non-Secured  Non-Secure chip and not able to change
> state
> +		RMA             Return Merchandise Authorization
> +		==============  =======================================
> ======
>  
>  What:		/sys/bus/platform/devices/MLNXBF04:00/post_rese
> t_wdog
>  Date:		Oct 2019
> @@ -25,10 +28,13 @@ KernelVersion:	5.5
>  Contact:	"Liming Sun <lsun@mellanox.com>"
>  Description:
>  		The source of the boot stream for the next reset. It
> could be
> -		one of the following values.
> -		  external - boot from external source (USB or PCIe)
> -		  emmc - boot from the onchip eMMC
> -		  emmc_legacy - boot from the onchip eMMC in legacy
> (slow) mode
> +		one of the following values:
> +
> +		===========  ==========================================
> =====
> +		external     boot from external source (USB or PCIe)
> +		emmc         boot from the onchip eMMC
> +		emmc_legacy  boot from the onchip eMMC in legacy (slow)
> mode
> +		===========  ==========================================
> =====
>  
>  What:		/sys/bus/platform/devices/MLNXBF04:00/second_re
> set_action
>  Date:		Oct 2019
> @@ -38,11 +44,14 @@ Description:
>  		Update the source of the boot stream after next reset.
> It could
>  		be one of the following values and will be applied
> after next
>  		reset.
> -		  external - boot from external source (USB or PCIe)
> -		  emmc - boot from the onchip eMMC
> -		  emmc_legacy - boot from the onchip eMMC in legacy
> (slow) mode
> -		  swap_emmc - swap the primary / secondary boot
> partition
> -		  none - cancel the action
> +
> +		===========  ==========================================
> =====
> +		external     boot from external source (USB or PCIe)
> +		emmc         boot from the onchip eMMC
> +		emmc_legacy  boot from the onchip eMMC in legacy (slow)
> mode
> +		swap_emmc    swap the primary / secondary boot
> partition
> +		none         cancel the action
> +		===========  ==========================================
> =====
>  
>  What:		/sys/bus/platform/devices/MLNXBF04:00/secure_bo
> ot_fuse_state
>  Date:		Oct 2019
> @@ -50,9 +59,12 @@ KernelVersion:	5.5
>  Contact:	"Liming Sun <lsun@mellanox.com>"
>  Description:
>  		The state of eFuse versions with the following values.
> -		  InUse - burnt, valid and currently in use
> -		  Used - burnt and valid
> -		  Free - not burnt and free to use
> -		  Skipped - not burnt but not free (skipped)
> -		  Wasted - burnt and invalid
> -		  Invalid - not burnt but marked as valid (error
> state).
> +
> +		=======  ==============================================
> =
> +		InUse    burnt, valid and currently in use
> +		Used     burnt and valid
> +		Free     not burnt and free to use
> +		Skipped  not burnt but not free (skipped)
> +		Wasted   burnt and invalid
> +		Invalid  not burnt but marked as valid (error state).
> +		=======  ==============================================
> =
> diff --git a/Documentation/ABI/testing/sysfs-platform-wilco-ec
> b/Documentation/ABI/testing/sysfs-platform-wilco-ec
> index 5f60b184a5a5..4439d0644091 100644
> --- a/Documentation/ABI/testing/sysfs-platform-wilco-ec
> +++ b/Documentation/ABI/testing/sysfs-platform-wilco-ec
> @@ -39,6 +39,7 @@ Description:
>                 which affects charging via the special USB PowerShare
> port
>                 (marked with a small lightning bolt or battery icon)
> when in
>                 low power states:
> +
>                 - In S0, the port will always provide power.
>                 - In S0ix, if usb_charge is enabled, then power will
> be
>                   supplied to the port when on AC or if battery is >
> 50%.