RE: [PATCH v2] Documentation: rapidio: move sysfs interface to ABI
From: Bounine, Alexandre
Date: Mon Feb 05 2018 - 13:19:59 EST
Sorry for the delay.
Acked-by: Alexandre Bounine <alexandre.bounine@xxxxxxx>
> -----Original Message-----
> From: Aishwarya Pant [mailto:aishpant@xxxxxxxxx]
> Sent: Friday, January 19, 2018 7:32 AM
> To: Matt Porter <mporter@xxxxxxxxxxxxxxxxxxx>; Bounine, Alexandre
> <Alexandre.Bounine@xxxxxxx>; Jonathan Corbet <corbet@xxxxxxx>; Greg
> KH <gregkh@xxxxxxxxxxxxxxxxxxx>; linux-doc@xxxxxxxxxxxxxxx; linux-
> kernel@xxxxxxxxxxxxxxx
> Cc: Julia Lawall <julia.lawall@xxxxxxx>
> 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@xxxxxxxxx>
> ---
> 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@xxxxxxxxxxxxxxxxxxx>,
> + Alexandre Bounine <alexandre.bounine@xxxxxxx>
> +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@xxxxxxxxxxxxxxxxxxx>,
> + Alexandre Bounine <alexandre.bounine@xxxxxxx>
> +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@xxxxxxxxxxxxxxxxxxx>,
> + Alexandre Bounine <alexandre.bounine@xxxxxxx>
> +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@xxxxxxxxxxxxxxxxxxx>,
> + Alexandre Bounine <alexandre.bounine@xxxxxxx>
> +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@xxxxxxxxxxxxxxxxxxx>,
> + Alexandre Bounine <alexandre.bounine@xxxxxxx>
> +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@xxxxxxxxxxxxxxxxxxx>,
> + Alexandre Bounine <alexandre.bounine@xxxxxxx>
> +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@xxxxxxxxxxxxxxxxxxx>,
> + Alexandre Bounine <alexandre.bounine@xxxxxxx>
> +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@xxxxxxxxxxxxxxxxxxx>,
> + Alexandre Bounine <alexandre.bounine@xxxxxxx>
> +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@xxxxxxxxxxxxxxxxxxx>,
> + Alexandre Bounine <alexandre.bounine@xxxxxxx>
> +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@xxxxxxxxxxxxxxxxxxx>,
> + Alexandre Bounine <alexandre.bounine@xxxxxxx>
> +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@xxxxxxxxxxxxxxxxxxx>,
> + Alexandre Bounine <alexandre.bounine@xxxxxxx>
> +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@xxxxxxxxxxxxxxxxxxx>,
> + Alexandre Bounine <alexandre.bounine@xxxxxxx>
> +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@xxxxxxxxxxxxxxxxxxx>,
> + Alexandre Bounine <alexandre.bounine@xxxxxxx>
> +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@xxxxxxxxxxxxxxxxxxx>,
> + Alexandre Bounine <alexandre.bounine@xxxxxxx>
> +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@xxxxxxxxxxxxxxxxxxx>,
> + Alexandre Bounine <alexandre.bounine@xxxxxxx>
> +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@xxxxxxxxxxxxxxxxxxx>,
> + Alexandre Bounine <alexandre.bounine@xxxxxxx>
> +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@xxxxxxxxxxxxxxxxxxx>,
> + Alexandre Bounine <alexandre.bounine@xxxxxxx>
> +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@xxxxxxxxxxxxxxxxxxx>,
> + Alexandre Bounine <alexandre.bounine@xxxxxxx>
> +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