Add some missing ABI symbols

PATCH In review Mauro Carvalho Chehab 2 participants 10 messages Sep 14, 2021 Documentation

lore

Share & tools

lore

Mauro Carvalho Chehab

author

2021-09-14 14:55 UTC #0 lore raw

v2 cover Add some missing ABI symbols

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

Signature · 1 line

2.31.1

Mauro Carvalho Chehab

author

2021-09-14 14:55 UTC #1 lore raw

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

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 <[email protected]>

---
 Documentation/ABI/stable/sysfs-module | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

Documentation/ABI/stable/sysfs-module +7 -6

index 6272ae5fb366..5c028af9921a 100644
@@ -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.

Signature · 1 line

2.31.1

Mauro Carvalho Chehab

author

2021-09-14 14:55 UTC #2 lore raw

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

In reply to 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 <[email protected]>

---
 Documentation/ABI/stable/sysfs-module | 12 ++++++++++++
 1 file changed, 12 insertions(+)

Documentation/ABI/stable/sysfs-module +12 -0

index 5c028af9921a..560b4a3278df 100644
@@ -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.

Signature · 1 line

2.31.1

Mauro Carvalho Chehab

author

2021-09-14 14:55 UTC #3 lore raw

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

In reply to 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 <[email protected]>

---
 Documentation/ABI/testing/sysfs-module | 7 +++++++
 1 file changed, 7 insertions(+)

Documentation/ABI/testing/sysfs-module +7 -0

index 88bddf192ceb..08886367d047 100644
@@ -41,6 +41,13 @@ KernelVersion:	3.3
 Contact:	Kay Sievers <[email protected]>
 Description:	Module size in bytes.
 
+What:		/sys/module/*/initstate
+Date:		Nov 2006
+KernelVersion:	2.6.19
+Contact:	Kay Sievers <[email protected]>
+Description:	Show the initialization state(live, coming, going) of
+		the module.
+
 What:		/sys/module/*/taint
 Date:		Jan 2012
 KernelVersion:	3.3

Signature · 1 line

2.31.1

Mauro Carvalho Chehab

author

2021-09-14 14:55 UTC #4 lore raw

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

In reply to 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 <[email protected]>

---
 Documentation/ABI/testing/sysfs-devices-power | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

Documentation/ABI/testing/sysfs-devices-power +14 -0

index 1763e64dd152..84694b8fec8e 100644
@@ -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 <[email protected]>
+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 <[email protected]>
+Description:
+		Reports total time that the device has been suspended.
+		Used for runtime PM statistics.

Signature · 1 line

2.31.1

Mauro Carvalho Chehab

author

2021-09-14 14:55 UTC #5 lore raw

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

In reply to 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 <[email protected]>

---
 Documentation/ABI/stable/sysfs-devices | 7 +++++++
 1 file changed, 7 insertions(+)

Documentation/ABI/stable/sysfs-devices +7 -0

index 42bf1eab5677..98a8ef99ac5f 100644
@@ -23,3 +23,10 @@ Contact:	Device Tree mailing list <[email protected]>
 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 <[email protected]>
+Description:
+		Major and minor numbers of the character device corresponding
+		to the device (in <major>:<minor> format).

Signature · 1 line

2.31.1

Mauro Carvalho Chehab

author

2021-09-14 14:55 UTC #6 lore raw

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

In reply to Mauro Carvalho Chehab

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

Signed-off-by Mauro Carvalho Chehab <[email protected]>

---
 Documentation/ABI/testing/sysfs-bus-pci | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

Documentation/ABI/testing/sysfs-bus-pci +17 -0

index 191cbe9ae5ed..1da4c8db3a9e 100644
@@ -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 <[email protected]>
+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:	[email protected]

Signature · 1 line

2.31.1

Bjorn Helgaas

Acked-by on v2 6/8

2021-09-14 18:58 UTC #7 lore raw

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

Quoted 4 lines · Mauro Carvalho Chehab

Even being available since 2005, there's no documentation for modalias.
Signed-off-by Mauro Carvalho Chehab <[email protected]>

Acked-by Bjorn Helgaas <[email protected]>

Quoted 35 lines

---
 Documentation/ABI/testing/sysfs-bus-pci | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

Documentation/ABI/testing/sysfs-bus-pci +17 -0

index 191cbe9ae5ed..1da4c8db3a9e 100644
@@ -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 <[email protected]>
+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:	[email protected]

Signature · 1 line

2.31.1

Mauro Carvalho Chehab

author

2021-09-14 14:55 UTC #8 lore raw

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

In reply to Mauro Carvalho Chehab

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

Signed-off-by Mauro Carvalho Chehab <[email protected]>

---
 Documentation/ABI/obsolete/o2cb | 11 +++++++++++
 Documentation/ABI/stable/o2cb   |  2 +-
 2 files changed, 12 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/ABI/obsolete/o2cb

Documentation/ABI/obsolete/o2cb new file +11 -0

new file mode 100644
index 000000000000..fe7e45e17bc7
@@ -0,0 +1,11 @@
+What:		/sys/o2cb
+Date:		Dec 2005
+KernelVersion:	2.6.16
+Contact:	[email protected]
+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
+		[email protected].

Documentation/ABI/stable/o2cb +1 -1

index 5eb1545e0b8d..b62a967f01a0 100644
@@ -1,4 +1,4 @@
-What:		/sys/fs/o2cb/ (was /sys/o2cb)
+What:		/sys/fs/o2cb/
 Date:		Dec 2005
 KernelVersion:	2.6.16
 Contact:	[email protected]

Signature · 1 line

2.31.1

Mauro Carvalho Chehab

author

2021-09-14 14:55 UTC #9 lore raw

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

In reply to 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 <[email protected]>

---
 Documentation/ABI/testing/sysfs-bus-usb | 43 +++++++++++++++++++++++--
 1 file changed, 41 insertions(+), 2 deletions(-)

Documentation/ABI/testing/sysfs-bus-usb +41 -2

index 42103f0f54d6..197698ad22af 100644
@@ -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

Signature · 1 line

2.31.1