Re: [PATCH] libata: transport: cleanup documentation of sysfs interface

[Tejun Heo]

On Tue, Feb 13, 2018 at 04:51:59PM +0530, Aishwarya Pant wrote:
> Clean-up the documentation of sysfs interfaces to be in the same format
> as described in Documentation/ABI/README. This will be useful for
> tracking changes in the ABI. Attributes are grouped by function (device,
> link or port) and then by date added.
> 
> This patch also adds documentation for one attribute -
> /sys/class/ata_port/ataX/port_no
> 
> Signed-off-by: Aishwarya Pant 

Applied to libata/for-4.16-fixes.

Thanks.

-- 
tejun

Re: [PATCH] libata: transport: cleanup documentation of sysfs interface

[Tejun Heo]

On Tue, Feb 13, 2018 at 04:51:59PM +0530, Aishwarya Pant wrote:
> Clean-up the documentation of sysfs interfaces to be in the same format
> as described in Documentation/ABI/README. This will be useful for
> tracking changes in the ABI. Attributes are grouped by function (device,
> link or port) and then by date added.
> 
> This patch also adds documentation for one attribute -
> /sys/class/ata_port/ataX/port_no
> 
> Signed-off-by: Aishwarya Pant 

Applied to libata/for-4.16-fixes.

Thanks.

-- 
tejun

[PATCH] libata: transport: cleanup documentation of sysfs interface

[Aishwarya Pant]

Clean-up the documentation of sysfs interfaces to be in the same format
as described in Documentation/ABI/README. This will be useful for
tracking changes in the ABI. Attributes are grouped by function (device,
link or port) and then by date added.

This patch also adds documentation for one attribute -
/sys/class/ata_port/ataX/port_no

Signed-off-by: Aishwarya Pant 
---
 Documentation/ABI/testing/sysfs-ata | 171 +---
 1 file changed, 100 insertions(+), 71 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-ata 
b/Documentation/ABI/testing/sysfs-ata
index aa4296498859..9ab0ef1dd1c7 100644
--- a/Documentation/ABI/testing/sysfs-ata
+++ b/Documentation/ABI/testing/sysfs-ata
@@ -1,110 +1,139 @@
 What:  /sys/class/ata_...
-Date:  August 2008
-Contact:   Gwendal Grignou
 Description:
-
-Provide a place in sysfs for storing the ATA topology of the system.  This 
allows
-retrieving various information about ATA objects.
+   Provide a place in sysfs for storing the ATA topology of the
+   system. This allows retrieving various information about ATA
+   objects.
 
 Files under /sys/class/ata_port
 ---
 
-   For each port, a directory ataX is created where X is the ata_port_id of
-   the port. The device parent is the ata host device.
+For each port, a directory ataX is created where X is the ata_port_id of the
+port. The device parent is the ata host device.
 
-idle_irq (read)
 
-   Number of IRQ received by the port while idle [some ata HBA only].
+What:  /sys/class/ata_port/ataX/nr_pmp_links
+What:  /sys/class/ata_port/ataX/idle_irq
+Date:  May, 2010
+KernelVersion: v2.6.37
+Contact:   Gwendal Grignou 
+Description:
+   nr_pmp_links:   (RO) If a SATA Port Multiplier (PM) is
+   connected, the number of links behind it.
 
-nr_pmp_links (read)
+   idle_irq:   (RO) Number of IRQ received by the port while
+   idle [some ata HBA only].
 
-   If a SATA Port Multiplier (PM) is connected, number of link behind it.
+
+What:  /sys/class/ata_port/ataX/port_no
+Date:  May, 2013
+KernelVersion: v3.11
+Contact:   Gwendal Grignou 
+Description:
+   (RO) Host local port number. While registering host controller,
+   port numbers are tracked based upon number of ports available on
+   the controller. This attribute is needed by udev for composing
+   persistent links in /dev/disk/by-path.
 
 Files under /sys/class/ata_link
 ---
 
-   Behind each port, there is a ata_link. If there is a SATA PM in the
-   topology, 15 ata_link objects are created.
-
-   If a link is behind a port, the directory name is linkX, where X is
-   ata_port_id of the port.
-   If a link is behind a PM, its name is linkX.Y where X is ata_port_id
-   of the parent port and Y the PM port.
+Behind each port, there is a ata_link. If there is a SATA PM in the topology, 
15
+ata_link objects are created.
 
-hw_sata_spd_limit
+If a link is behind a port, the directory name is linkX, where X is ata_port_id
+of the port. If a link is behind a PM, its name is linkX.Y where X is
+ata_port_id of the parent port and Y the PM port.
 
-   Maximum speed supported by the connected SATA device.
 
-sata_spd_limit
+What:  /sys/class/ata_link/linkX[.Y]/hw_sata_spd_limit
+What:  /sys/class/ata_link/linkX[.Y]/sata_spd_limit
+What:  /sys/class/ata_link/linkX[.Y]/sata_spd
+Date:  May, 2010
+KernelVersion: v2.6.37
+Contact:   Gwendal Grignou 
+Description:
+   hw_sata_spd_limit:  (RO) Maximum speed supported by the
+   connected SATA device.
 
-   Maximum speed imposed by libata.
+   sata_spd_limit: (RO) Maximum speed imposed by libata.
 
-sata_spd
+   sata_spd:   (RO) Current speed of the link
+   eg. 1.5, 3 Gbps etc.
 
-   Current speed of the link [1.5, 3Gps,...].
 
 Files under /sys/class/ata_device
 -
 
-   Behind each link, up to two ata device are created.
-   The name of the directory is devX[.Y].Z where:
-   - X is ata_port_id of the port where the device is connected,
-   - Y the port of the PM if any, and
-   - Z the device id: for PATA, there is usually 2 devices [0,1],
-   only 1 for SATA.
-
-class
-   Device class. Can be "ata" for disk, "atapi" for packet device,
-   "pmp" for PM, or "none" if no device was found behind the link.
-
-dma_mode
+Behind each link, up to two ata devices are created.
+The name of the directory is devX[.Y].Z where:
+- X is 

[PATCH] libata: transport: cleanup documentation of sysfs interface

[Aishwarya Pant]

Clean-up the documentation of sysfs interfaces to be in the same format
as described in Documentation/ABI/README. This will be useful for
tracking changes in the ABI. Attributes are grouped by function (device,
link or port) and then by date added.

This patch also adds documentation for one attribute -
/sys/class/ata_port/ataX/port_no

Signed-off-by: Aishwarya Pant 
---
 Documentation/ABI/testing/sysfs-ata | 171 +---
 1 file changed, 100 insertions(+), 71 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-ata 
b/Documentation/ABI/testing/sysfs-ata
index aa4296498859..9ab0ef1dd1c7 100644
--- a/Documentation/ABI/testing/sysfs-ata
+++ b/Documentation/ABI/testing/sysfs-ata
@@ -1,110 +1,139 @@
 What:  /sys/class/ata_...
-Date:  August 2008
-Contact:   Gwendal Grignou
 Description:
-
-Provide a place in sysfs for storing the ATA topology of the system.  This 
allows
-retrieving various information about ATA objects.
+   Provide a place in sysfs for storing the ATA topology of the
+   system. This allows retrieving various information about ATA
+   objects.
 
 Files under /sys/class/ata_port
 ---
 
-   For each port, a directory ataX is created where X is the ata_port_id of
-   the port. The device parent is the ata host device.
+For each port, a directory ataX is created where X is the ata_port_id of the
+port. The device parent is the ata host device.
 
-idle_irq (read)
 
-   Number of IRQ received by the port while idle [some ata HBA only].
+What:  /sys/class/ata_port/ataX/nr_pmp_links
+What:  /sys/class/ata_port/ataX/idle_irq
+Date:  May, 2010
+KernelVersion: v2.6.37
+Contact:   Gwendal Grignou 
+Description:
+   nr_pmp_links:   (RO) If a SATA Port Multiplier (PM) is
+   connected, the number of links behind it.
 
-nr_pmp_links (read)
+   idle_irq:   (RO) Number of IRQ received by the port while
+   idle [some ata HBA only].
 
-   If a SATA Port Multiplier (PM) is connected, number of link behind it.
+
+What:  /sys/class/ata_port/ataX/port_no
+Date:  May, 2013
+KernelVersion: v3.11
+Contact:   Gwendal Grignou 
+Description:
+   (RO) Host local port number. While registering host controller,
+   port numbers are tracked based upon number of ports available on
+   the controller. This attribute is needed by udev for composing
+   persistent links in /dev/disk/by-path.
 
 Files under /sys/class/ata_link
 ---
 
-   Behind each port, there is a ata_link. If there is a SATA PM in the
-   topology, 15 ata_link objects are created.
-
-   If a link is behind a port, the directory name is linkX, where X is
-   ata_port_id of the port.
-   If a link is behind a PM, its name is linkX.Y where X is ata_port_id
-   of the parent port and Y the PM port.
+Behind each port, there is a ata_link. If there is a SATA PM in the topology, 
15
+ata_link objects are created.
 
-hw_sata_spd_limit
+If a link is behind a port, the directory name is linkX, where X is ata_port_id
+of the port. If a link is behind a PM, its name is linkX.Y where X is
+ata_port_id of the parent port and Y the PM port.
 
-   Maximum speed supported by the connected SATA device.
 
-sata_spd_limit
+What:  /sys/class/ata_link/linkX[.Y]/hw_sata_spd_limit
+What:  /sys/class/ata_link/linkX[.Y]/sata_spd_limit
+What:  /sys/class/ata_link/linkX[.Y]/sata_spd
+Date:  May, 2010
+KernelVersion: v2.6.37
+Contact:   Gwendal Grignou 
+Description:
+   hw_sata_spd_limit:  (RO) Maximum speed supported by the
+   connected SATA device.
 
-   Maximum speed imposed by libata.
+   sata_spd_limit: (RO) Maximum speed imposed by libata.
 
-sata_spd
+   sata_spd:   (RO) Current speed of the link
+   eg. 1.5, 3 Gbps etc.
 
-   Current speed of the link [1.5, 3Gps,...].
 
 Files under /sys/class/ata_device
 -
 
-   Behind each link, up to two ata device are created.
-   The name of the directory is devX[.Y].Z where:
-   - X is ata_port_id of the port where the device is connected,
-   - Y the port of the PM if any, and
-   - Z the device id: for PATA, there is usually 2 devices [0,1],
-   only 1 for SATA.
-
-class
-   Device class. Can be "ata" for disk, "atapi" for packet device,
-   "pmp" for PM, or "none" if no device was found behind the link.
-
-dma_mode
+Behind each link, up to two ata devices are created.
+The name of the directory is devX[.Y].Z where:
+- X is ata_port_id of the port where the device is connected,
+- Y the port of the PM if any, and
+- Z the device id: for