[PATCH v2 0/8] Add some missing ABI symbols

[PATCH v2 0/8] Add some missing ABI symbols

[Mauro Carvalho Chehab]

Hi Greg,

This series contain some things I detected when using scripts/get_abi.pl.

Most of the patches here add documentation for some symbols that
were upstreamed a long time ago, but, up to today, they weren't
defined.

There are still a lot to be addressed, as, at least on my desktop, there are
8k+ undefined symbols:

	./scripts/get_abi.pl undefined|wc -l
	   8792

Mauro Carvalho Chehab (8):
  ABI: stable/sysfs-module: better document modules
  ABI: stable/sysfs-module: document version and srcversion
  ABI: testing/sysfs-module: document initstate
  ABI: sysfs-devices-power: document some RPM statistics
  ABI: sysfs-devices: add /dev ABI
  ABI: sysfs-bus-pci: add documentation for modalias
  ABI: o2cb: add an obsolete file for /sys/o2cb
  ABI: sysfs-bus-usb: add some missing definitions

 Documentation/ABI/obsolete/o2cb               | 11 +++++
 Documentation/ABI/stable/o2cb                 |  2 +-
 Documentation/ABI/stable/sysfs-devices        |  7 +++
 Documentation/ABI/stable/sysfs-module         | 25 ++++++++---
 Documentation/ABI/testing/sysfs-bus-pci       | 17 ++++++++
 Documentation/ABI/testing/sysfs-bus-usb       | 43 ++++++++++++++++++-
 Documentation/ABI/testing/sysfs-devices-power | 14 ++++++
 Documentation/ABI/testing/sysfs-module        |  7 +++
 8 files changed, 117 insertions(+), 9 deletions(-)
 create mode 100644 Documentation/ABI/obsolete/o2cb

-- 
2.31.1

[PATCH v2 1/8] ABI: stable/sysfs-module: better document modules

[Mauro Carvalho Chehab]

Instead of placing almost everything there as a text, use
the proper What: for each component of the ABI.

This allows it to be better documented and parsed by
get_abi.pl.

While here, use wildcards for MODULENAME.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/stable/sysfs-module | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/Documentation/ABI/stable/sysfs-module b/Documentation/ABI/stable/sysfs-module
index 6272ae5fb366..5c028af9921a 100644
--- a/Documentation/ABI/stable/sysfs-module
+++ b/Documentation/ABI/stable/sysfs-module
@@ -1,8 +1,7 @@
-What:		/sys/module
-Description:
-	The /sys/module tree consists of the following structure:
+The /sys/module tree consists of the following structure:
 
-	/sys/module/MODULENAME
+What:		/sys/module/<MODULENAME>
+Description:
 		The name of the module that is in the kernel.  This
 		module name will always show up if the module is loaded as a
 		dynamic module.  If it is built directly into the kernel, it
@@ -12,7 +11,8 @@ Description:
 		Note: The conditions of creation in the built-in case are not
 		by design and may be removed in the future.
 
-	/sys/module/MODULENAME/parameters
+What:		/sys/module/<MODULENAME>/parameters
+Description:
 		This directory contains individual files that are each
 		individual parameters of the module that are able to be
 		changed at runtime.  See the individual module
@@ -25,7 +25,8 @@ Description:
 		individual driver documentation for details as to the
 		stability of the different parameters.
 
-	/sys/module/MODULENAME/refcnt
+What:		/sys/module/<MODULENAME>/refcnt
+Description:
 		If the module is able to be unloaded from the kernel, this file
 		will contain the current reference count of the module.
 
-- 
2.31.1

[PATCH v2 2/8] ABI: stable/sysfs-module: document version and srcversion

[Mauro Carvalho Chehab]

Changeset c988d2b28454 ("[PATCH] modules: add version and srcversion to sysfs")
added version and srcversion ABI to modules. Document them.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/stable/sysfs-module | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Documentation/ABI/stable/sysfs-module b/Documentation/ABI/stable/sysfs-module
index 5c028af9921a..560b4a3278df 100644
--- a/Documentation/ABI/stable/sysfs-module
+++ b/Documentation/ABI/stable/sysfs-module
@@ -33,3 +33,15 @@ Description:
 		Note: If the module is built into the kernel, or if the
 		CONFIG_MODULE_UNLOAD kernel configuration value is not enabled,
 		this file will not be present.
+
+What:		/sys/module/<MODULENAME>/srcversion
+Date:		Jun 2005
+Description:
+		If the module source has MODULE_VERSION, this file will contain
+		the checksum of the the source code.
+
+What:		/sys/module/<MODULENAME>/version
+Date:		Jun 2005
+Description:
+		If the module source has MODULE_VERSION, this file will contain
+		the version of the source code.
-- 
2.31.1

[PATCH v2 3/8] ABI: testing/sysfs-module: document initstate

[Mauro Carvalho Chehab]

Despite being an old ABI, present on all modules, its documentation
is missing. Add it, based on the original commit.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/testing/sysfs-module | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-module b/Documentation/ABI/testing/sysfs-module
index 88bddf192ceb..08886367d047 100644
--- a/Documentation/ABI/testing/sysfs-module
+++ b/Documentation/ABI/testing/sysfs-module
@@ -41,6 +41,13 @@ KernelVersion:	3.3
 Contact:	Kay Sievers <kay.sievers@vrfy.org>
 Description:	Module size in bytes.
 
+What:		/sys/module/*/initstate
+Date:		Nov 2006
+KernelVersion:	2.6.19
+Contact:	Kay Sievers <kay.sievers@vrfy.org>
+Description:	Show the initialization state(live, coming, going) of
+		the module.
+
 What:		/sys/module/*/taint
 Date:		Jan 2012
 KernelVersion:	3.3
-- 
2.31.1

[PATCH v2 4/8] ABI: sysfs-devices-power: document some RPM statistics

[Mauro Carvalho Chehab]

Changeset 8d4b9d1bfef1 ("PM / Runtime: Add runtime PM statistics (v3)")
added runtime_active_time and runtime_suspended_time, in order
to allow powertop to identify the amount of time a device is
active/suspended.

Add an ABI description for those.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/testing/sysfs-devices-power | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-devices-power b/Documentation/ABI/testing/sysfs-devices-power
index 1763e64dd152..84694b8fec8e 100644
--- a/Documentation/ABI/testing/sysfs-devices-power
+++ b/Documentation/ABI/testing/sysfs-devices-power
@@ -269,3 +269,17 @@ Description:
 		the current runtime PM status of the device, which may be
 		"suspended", "suspending", "resuming", "active", "error" (fatal
 		error), or "unsupported" (runtime PM is disabled).
+
+What:		/sys/devices/.../power/runtime_active_time
+Date:		Jul 2010
+Contact:	Arjan van de Ven <arjan@linux.intel.com>
+Description:
+		Reports the total time that the device has been active.
+		Used for runtime PM statistics.
+
+What:		/sys/devices/.../power/runtime_suspended_time
+Date:		Jul 2010
+Contact:	Arjan van de Ven <arjan@linux.intel.com>
+Description:
+		Reports total time that the device has been suspended.
+		Used for runtime PM statistics.
-- 
2.31.1

[PATCH v2 5/8] ABI: sysfs-devices: add /dev ABI

[Mauro Carvalho Chehab]

Changeset 23681e479129 ("[PATCH] Driver core: allow struct device to have a dev_t")
added a /dev ABI for /sys/devices. Document it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/stable/sysfs-devices | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/ABI/stable/sysfs-devices b/Documentation/ABI/stable/sysfs-devices
index 42bf1eab5677..98a8ef99ac5f 100644
--- a/Documentation/ABI/stable/sysfs-devices
+++ b/Documentation/ABI/stable/sysfs-devices
@@ -23,3 +23,10 @@ Contact:	Device Tree mailing list <devicetree@vger.kernel.org>
 Description:
 		If CONFIG_OF is enabled, then this file is present. When
 		read, it returns full name of the device node.
+
+What:		/sys/devices/*/dev
+Date:		Jun 2006
+Contact:	Greg Kroah-Hartman <gregkh@linuxfoundation.org>
+Description:
+		Major and minor numbers of the character device corresponding
+		to the device (in <major>:<minor> format).
-- 
2.31.1

[PATCH v2 6/8] ABI: sysfs-bus-pci: add documentation for modalias

[Mauro Carvalho Chehab]

Even being available since 2005, there's no documentation for
modalias.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/testing/sysfs-bus-pci | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci
index 191cbe9ae5ed..1da4c8db3a9e 100644
--- a/Documentation/ABI/testing/sysfs-bus-pci
+++ b/Documentation/ABI/testing/sysfs-bus-pci
@@ -187,6 +187,23 @@ Description:
 		The symbolic link points to the PCI device sysfs entry of the
 		Physical Function this device associates with.
 
+What:		/sys/bus/pci/devices/.../modalias
+Date:		May 2005
+Contact:	Greg Kroah-Hartman <gregkh@linuxfoundation.org>
+Description:
+		This attribute indicates the PCI ID of the device object.
+
+		That is in the format:
+		pci:vXXXXXXXXdXXXXXXXXsvXXXXXXXXsdXXXXXXXXbcXXscXXiXX,
+		where:
+		    - vXXXXXXXX contains the vendor ID;
+		    - dXXXXXXXX contains the device ID;
+		    - svXXXXXXXX contains the sub-vendor ID;
+		    - sdXXXXXXXX contains the subsystem device ID;
+		    - bcXX contains the device class;
+		    - scXX contains the device subclass;
+		    - iXX contains the device class programming interface.
+
 What:		/sys/bus/pci/slots/.../module
 Date:		June 2009
 Contact:	linux-pci@vger.kernel.org
-- 
2.31.1

[PATCH v2 7/8] ABI: o2cb: add an obsolete file for /sys/o2cb

[Mauro Carvalho Chehab]

This was renamed to /sys/fs/o2cb. Mark the old name as
obsolete.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/obsolete/o2cb | 11 +++++++++++
 Documentation/ABI/stable/o2cb   |  2 +-
 2 files changed, 12 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/ABI/obsolete/o2cb

diff --git a/Documentation/ABI/obsolete/o2cb b/Documentation/ABI/obsolete/o2cb
new file mode 100644
index 000000000000..fe7e45e17bc7
--- /dev/null
+++ b/Documentation/ABI/obsolete/o2cb
@@ -0,0 +1,11 @@
+What:		/sys/o2cb
+Date:		Dec 2005
+KernelVersion:	2.6.16
+Contact:	ocfs2-devel@oss.oracle.com
+Description:	Ocfs2-tools looks at 'interface-revision' for versioning
+		information. Each logmask/ file controls a set of debug prints
+		and can be written into with the strings "allow", "deny", or
+		"off". Reading the file returns the current state.
+		Was renamed to /sys/fs/u2cb/
+Users:		ocfs2-tools. It's sufficient to mail proposed changes to
+		ocfs2-devel@oss.oracle.com.
diff --git a/Documentation/ABI/stable/o2cb b/Documentation/ABI/stable/o2cb
index 5eb1545e0b8d..b62a967f01a0 100644
--- a/Documentation/ABI/stable/o2cb
+++ b/Documentation/ABI/stable/o2cb
@@ -1,4 +1,4 @@
-What:		/sys/fs/o2cb/ (was /sys/o2cb)
+What:		/sys/fs/o2cb/
 Date:		Dec 2005
 KernelVersion:	2.6.16
 Contact:	ocfs2-devel@oss.oracle.com
-- 
2.31.1

[PATCH v2 8/8] ABI: sysfs-bus-usb: add some missing definitions

[Mauro Carvalho Chehab]

There are lots of interface and endpoint properties that
are currently missing any documentation. Add a basic one
for them.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/testing/sysfs-bus-usb | 43 +++++++++++++++++++++++--
 1 file changed, 41 insertions(+), 2 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb
index 42103f0f54d6..197698ad22af 100644
--- a/Documentation/ABI/testing/sysfs-bus-usb
+++ b/Documentation/ABI/testing/sysfs-bus-usb
@@ -1,4 +1,4 @@
-What:		/sys/bus/usb/devices/INTERFACE/authorized
+What:		/sys/bus/usb/devices/<INTERFACE>/authorized
 Date:		August 2015
 Description:
 		This allows to authorize (1) or deauthorize (0)
@@ -12,7 +12,46 @@ Description:
 
 		A deauthorized interface cannot be probed or claimed.
 
-What:		/sys/bus/usb/devices/usbX/interface_authorized_default
+What:		/sys/bus/usb/devices/<INTERFACE>/bAlternateSetting
+What:		/sys/bus/usb/devices/<INTERFACE>/bcdDevice
+What:		/sys/bus/usb/devices/<INTERFACE>/bConfigurationValue
+What:		/sys/bus/usb/devices/<INTERFACE>/bDeviceClass
+What:		/sys/bus/usb/devices/<INTERFACE>/bDeviceProtocol
+What:		/sys/bus/usb/devices/<INTERFACE>/bDeviceSubClass
+What:		/sys/bus/usb/devices/<INTERFACE>/bAlternateSetting
+What:		/sys/bus/usb/devices/<INTERFACE>/bInterfaceClass
+What:		/sys/bus/usb/devices/<INTERFACE>/bInterfaceNumber
+What:		/sys/bus/usb/devices/<INTERFACE>/bInterfaceProtocol
+What:		/sys/bus/usb/devices/<INTERFACE>/bInterfaceSubClass
+What:		/sys/bus/usb/devices/<INTERFACE>/bmAttributes
+What:		/sys/bus/usb/devices/<INTERFACE>/bMaxPacketSize0
+What:		/sys/bus/usb/devices/<INTERFACE>/bMaxPower
+What:		/sys/bus/usb/devices/<INTERFACE>/bNumConfigurations
+What:		/sys/bus/usb/devices/<INTERFACE>/bNumEndpoints
+What:		/sys/bus/usb/devices/<INTERFACE>/bNumInterfaces
+What:		/sys/bus/usb/devices/<INTERFACE>/busnum
+What:		/sys/bus/usb/devices/<INTERFACE>/configuration
+What:		/sys/bus/usb/devices/<INTERFACE>/descriptors
+What:		/sys/bus/usb/devices/<INTERFACE>/bNumEndpoints
+What:		/sys/bus/usb/devices/<INTERFACE>/idProduct
+What:		/sys/bus/usb/devices/<INTERFACE>/idVendor
+
+Description:
+		Contain the corresponding USB descriptors for <INTERFACE>.
+
+What:		/sys/bus/usb/devices/<INTERFACE>/ep_<N>/bEndpointAddress
+What:		/sys/bus/usb/devices/<INTERFACE>/ep_<N>/bInterval
+What:		/sys/bus/usb/devices/<INTERFACE>/ep_<N>/bLength
+What:		/sys/bus/usb/devices/<INTERFACE>/ep_<N>/bmAttributes
+What:		/sys/bus/usb/devices/<INTERFACE>/ep_<N>/direction
+What:		/sys/bus/usb/devices/<INTERFACE>/ep_<N>/interval
+What:		/sys/bus/usb/devices/<INTERFACE>/ep_<N>/type
+What:		/sys/bus/usb/devices/<INTERFACE>/ep_<N>/wMaxPacketSize
+Description:
+		Contain the corresponding USB descriptors for the USB
+		endpoint ep_<N>.
+
+What:		/sys/bus/usb/devices/usb<X>/interface_authorized_default
 Date:		August 2015
 Description:
 		This is used as value that determines if interfaces
-- 
2.31.1

Re: [PATCH v2 6/8] ABI: sysfs-bus-pci: add documentation for modalias

[Bjorn Helgaas]

On Tue, Sep 14, 2021 at 04:55:19PM +0200, Mauro Carvalho Chehab wrote:
> Even being available since 2005, there's no documentation for
> modalias.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Acked-by: Bjorn Helgaas <bhelgaas@google.com>

> ---
>  Documentation/ABI/testing/sysfs-bus-pci | 17 +++++++++++++++++
>  1 file changed, 17 insertions(+)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci
> index 191cbe9ae5ed..1da4c8db3a9e 100644
> --- a/Documentation/ABI/testing/sysfs-bus-pci
> +++ b/Documentation/ABI/testing/sysfs-bus-pci
> @@ -187,6 +187,23 @@ Description:
>  		The symbolic link points to the PCI device sysfs entry of the
>  		Physical Function this device associates with.
>  
> +What:		/sys/bus/pci/devices/.../modalias
> +Date:		May 2005
> +Contact:	Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> +Description:
> +		This attribute indicates the PCI ID of the device object.
> +
> +		That is in the format:
> +		pci:vXXXXXXXXdXXXXXXXXsvXXXXXXXXsdXXXXXXXXbcXXscXXiXX,
> +		where:
> +		    - vXXXXXXXX contains the vendor ID;
> +		    - dXXXXXXXX contains the device ID;
> +		    - svXXXXXXXX contains the sub-vendor ID;
> +		    - sdXXXXXXXX contains the subsystem device ID;
> +		    - bcXX contains the device class;
> +		    - scXX contains the device subclass;
> +		    - iXX contains the device class programming interface.
> +
>  What:		/sys/bus/pci/slots/.../module
>  Date:		June 2009
>  Contact:	linux-pci@vger.kernel.org
> -- 
> 2.31.1
>