Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
From:   "Bounine, Alexandre" <Alexandre.Bounine@idt.com>
To:     Aishwarya Pant <aishpant@gmail.com>,
        Matt Porter <mporter@kernel.crashing.org>,
        Jonathan Corbet <corbet@lwn.net>,
        Greg KH <gregkh@linuxfoundation.org>,
        "linux-doc@vger.kernel.org" <linux-doc@vger.kernel.org>,
        "linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>
CC:     Julia Lawall <julia.lawall@lip6.fr>
Subject: RE: [PATCH v2] Documentation: rapidio: move sysfs interface to ABI
Thread-Topic: [PATCH v2] Documentation: rapidio: move sysfs interface to ABI
Thread-Index: AQHTkSF/crguIcEBvUqV6eBisw+Qm6OWOV3g
Date:   Mon, 5 Feb 2018 18:19:32 +0000
Message-ID: <8D983423E7EDF846BB3056827B8CC5D161B46CE5@corpmail1>
References: <20180119123147.GA17446@mordor.localdomain>
In-Reply-To: <20180119123147.GA17446@mordor.localdomain>
Accept-Language: en-US
Content-Language: en-US
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 8BIT
MIME-Version: 1.0
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

Sorry for the delay.

Acked-by: Alexandre Bounine <alexandre.bounine@idt.com>

> -----Original Message-----
> From: Aishwarya Pant [mailto:aishpant@gmail.com]
> Sent: Friday, January 19, 2018 7:32 AM
> To: Matt Porter <mporter@kernel.crashing.org>; Bounine, Alexandre
> <Alexandre.Bounine@idt.com>; Jonathan Corbet <corbet@lwn.net>; Greg
> KH <gregkh@linuxfoundation.org>; linux-doc@vger.kernel.org; linux-
> kernel@vger.kernel.org
> Cc: Julia Lawall <julia.lawall@lip6.fr>
> Subject: [PATCH v2] Documentation: rapidio: move sysfs interface to ABI
> 
> Right now, the description of the rapidio sysfs interfaces is in
> Documentation/rapidio/sysfs.txt. Since these are a part of the ABI, they
> should be in Documentation/ABI along with the rest.
> 
> Signed-off-by: Aishwarya Pant <aishpant@gmail.com>
> ---
> Movement of sysfs interface is not absolutely necessary but this format
> adds some metadata (like kernel version, added date) which might be
> useful in scripting and tracking changes.
> 
> Changes in v2:
> -Fix typo typr -> typo
> -Add context around enumerating devices' destid
> -Add destid attribute to list of common attributes
> -Edit description of binary attribute config
> -Add a line in Documentation/rapidio/sysfs.txt about movement of the
>  sysfs ABI
> 
>  Documentation/ABI/testing/sysfs-bus-rapidio   | 198
> ++++++++++++++++++++++++++
>  Documentation/ABI/testing/sysfs-class-rapidio |  55 +++++++
>  Documentation/rapidio/sysfs.txt               | 161 +--------------------
>  3 files changed, 256 insertions(+), 158 deletions(-)
>  create mode 100644 Documentation/ABI/testing/sysfs-bus-rapidio
>  create mode 100644 Documentation/ABI/testing/sysfs-class-rapidio
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-rapidio
> b/Documentation/ABI/testing/sysfs-bus-rapidio
> new file mode 100644
> index 000000000000..13208b27dd87
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-bus-rapidio
> @@ -0,0 +1,198 @@
> +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.
> diff --git a/Documentation/ABI/testing/sysfs-class-rapidio
> b/Documentation/ABI/testing/sysfs-class-rapidio
> new file mode 100644
> index 000000000000..8716beeb16c1
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-class-rapidio
> @@ -0,0 +1,55 @@
> +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
> diff --git a/Documentation/rapidio/sysfs.txt
> b/Documentation/rapidio/sysfs.txt
> index 47ce9a5336e1..a1adac888e6e 100644
> --- a/Documentation/rapidio/sysfs.txt
> +++ b/Documentation/rapidio/sysfs.txt
> @@ -1,158 +1,3 @@
> -                         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
> --
> 2.16.0