Re: [PATCH 2/2] Documentation/ABI: Move the topology-related sysfs interface to the right place - Linuxarm

26 Apr 2021

...
-----Original Message-----
From: tiantao (H)
Sent: Monday, April 26, 2021 2:26 PM
To: Song Bao Hua (Barry Song) song.bao.hua@hisilicon.com
Cc: linuxarm@openeuler.org; tiantao (H) tiantao6@hisilicon.com
Subject: [PATCH 2/2] Documentation/ABI: Move the topology-related sysfs
interface to the right place
Move the interface that exists under
/sys/devices/system/cpu/cpuX/topology/ to the more logical
Documentation/ABI/ file that can be properly parsed and
displayed to the user space
Signed-off-by: Tian Tao tiantao6@hisilicon.com
Signed-off-by: Barry Song song.bao.hua@hisilicon.com

Documentation/ABI/stable/sysfs-devices-system-cpu | 149
++++++++++++++++++++++
 Documentation/admin-guide/cputopology.rst         | 104 ---------------
 2 files changed, 149 insertions(+), 104 deletions(-)

diff --git a/Documentation/ABI/stable/sysfs-devices-system-cpu
b/Documentation/ABI/stable/sysfs-devices-system-cpu
index 33c133e..7d0b23e 100644
--- a/Documentation/ABI/stable/sysfs-devices-system-cpu
+++ b/Documentation/ABI/stable/sysfs-devices-system-cpu
@@ -1,3 +1,7 @@
+Export CPU topology info via sysfs. Items (attributes) are similar
+to /proc/cpuinfo output of some architectures.  They reside in
+/sys/devices/system/cpu/cpuX/topology/:



What: 		/sys/devices/system/cpu/dscr_default
 Date:		13-May-2014
 KernelVersion:	v3.15.0
@@ -23,3 +27,148 @@ Description:	Default value for the Data Stream Control
Register (DSCR) on
   	here).
   	If set by a process it will be inherited by child processes.
 Values:		64 bit unsigned integer (bit field)



+What:           /sys/devices/system/cpu/cpuX/topology/physical_package_id
+Date:           19-Mar-2021
+KernelVersion:  v5.12
+Contact:
+Description:    physical package id of cpuX. Typically corresponds to a
physical

           socket number, but the actual value is architecture and platform


           dependent.



+Values:         64 bit unsigned integer (bit field)



+What:           /sys/devices/system/cpu/cpuX/topology/die_id
+Date:           19-Mar-2021
+KernelVersion:  v5.12
+Contact:
+Description:    the CPU die ID of cpuX. Typically it is the hardware platform's

           identifier (rather than the kernel's).  The actual value is


           architecture and platform dependent.



+Values:         64 bit unsigned integer (bit field)



+What:           /sys/devices/system/cpu/cpuX/topology/core_id
+Date:           19-Mar-2021
+KernelVersion:  v5.12
+Contact:
+Description:    the CPU core ID of cpuX. Typically it is the hardware platform's

           identifier (rather than the kernel's).  The actual value is


           architecture and platform dependent.



+Values:         64 bit unsigned integer (bit field)



+What:           /sys/devices/system/cpu/cpuX/topology/book_id
+Date:           19-Mar-2021
+KernelVersion:  v5.12
+Contact:
+Description:    the book ID of cpuX. Typically it is the hardware platform's

           identifier (rather than the kernel's).	The actual value is


           architecture and platform dependent.



+Values:         64 bit unsigned integer (bit field)



+What:           /sys/devices/system/cpu/cpuX/topology/drawer_id
+Date:           19-Mar-2021
+KernelVersion:  v5.12
+Contact:
+Description:    the drawer ID of cpuX. Typically it is the hardware platform's

           identifier (rather than the kernel's).  The actual value is


           architecture and platform dependent.



+Values:         64 bit unsigned integer (bit field)



+What:           /sys/devices/system/cpu/cpuX/topology/core_cpus
+Date:           19-Mar-2021
+KernelVersion:  v5.12
+Contact:
+Description:    internal kernel map of CPUs within the same core.

           (deprecated name: "thread_siblings")



+Values:         hexadecimal bitmask.



+What:           /sys/devices/system/cpu/cpuX/topology/core_cpus_list
+Date:           19-Mar-2021
+KernelVersion:  v5.12
+Contact:
+Description:    human-readable list of CPUs within the same core.

           The format is like 0-3, 8-11, 14,17. The maximum size is PAGE_SIZE,


       so the tail of the string will be trimmed while its size is larger


           than PAGE_SIZE.


           (deprecated name: "thread_siblings_list").



+Values:         hexadecimal bitmask.
No. this is a list not a mask.
...



+What:           /sys/devices/system/cpu/cpuX/topology/package_cpus
+Date:           19-Mar-2021
+KernelVersion:  v5.12
+Contact:
+Description:    internal kernel map of the CPUs sharing the same
physical_package_id.

           (deprecated name: "core_siblings").



+Values:         64 bit unsigned integer (bit field)
Id is unsigned integer. Here it is hexadecimal bitmask.
...



+What:           /sys/devices/system/cpu/cpuX/topology/package_cpus_list
+Date:           19-Mar-2021
+KernelVersion:  v5.12
+Contact:
+Description:    human-readable list of CPUs sharing the same
physical_package_id.

           The format is like 0-3, 8-11, 14,17. The maximum size is PAGE_SIZE,


           so the tail of the string will be trimmed while its size is larger


           than PAGE_SIZE.


           (deprecated name: "core_siblings_list")



+Values:         hexadecimal bitmask.
As above.
...



+What:           /sys/devices/system/cpu/cpuX/topology/die_cpus
+Date:           19-Mar-2021
+KernelVersion:  v5.12
+Contact:
+Description:    internal kernel map of CPUs within the same die.
+Values:         64 bit unsigned integer (bit field)
As above.
...



+What:           /sys/devices/system/cpu/cpuX/topology/die_cpus_list
+Date:           19-Mar-2021
+KernelVersion:  v5.12
+Contact:
+Description:    human-readable list of CPUs within the same die.

           The format is like 0-3, 8-11, 14,17. The maximum size is PAGE_SIZE,


           so the tail of the string will be trimmed while its size is larger


           than PAGE_SIZE.



+Values:         hexadecimal bitmask.
As above.
...



+What:           /sys/devices/system/cpu/cpuX/topology/book_siblings
+Date:           19-Mar-2021
+KernelVersion:  v5.12
+Contact:
+Description:    internal kernel map of cpuX's hardware threads within the same

           book_id.



+Values:         64 bit unsigned integer (bit field)
As above.
...



+What:           /sys/devices/system/cpu/cpuX/topology/book_siblings_list
+Date:           19-Mar-2021
+KernelVersion:  v5.12
+Contact:
+Description:    human-readable list of cpuX's hardware threads within the same

           book_id.


           The format is like 0-3, 8-11, 14,17. The maximum size is PAGE_SIZE,


           so the tail of the string will be trimmed while its size is larger


           than PAGE_SIZE.



For example here we should mark it "available to s390 only"
...
+Values:         hexadecimal bitmask.



+What:           /sys/devices/system/cpu/cpuX/topology/drawer_siblings
+Date:           19-Mar-2021
+KernelVersion:  v5.12
+Contact:
+Description:    internal kernel map of cpuX's hardware threads within the same

           drawer_id.



+Values:         64 bit unsigned integer (bit field)



+What:           /sys/devices/system/cpu/cpuX/topology/drawer_siblings_list
+Date:           19-Mar-2021
+KernelVersion:  v5.12
+Contact:
+Description:    human-readable list of cpuX's hardware threads within the same

           drawer_id.


           The format is like 0-3, 8-11, 14,17. The maximum size is PAGE_SIZE,


           so the tail of the string will be trimmed while its size is larger


           than PAGE_SIZE.



+Values:         hexadecimal bitmask.



+Architecture-neutral, drivers/base/topology.c, exports these attributes.
+However, the book and drawer related sysfs files will only be created if
+CONFIG_SCHED_BOOK and CONFIG_SCHED_DRAWER are selected, respectively.



+CONFIG_SCHED_BOOK and CONFIG_SCHED_DRAWER are currently only used on s390,
+where they reflect the cpu and cache hierarchy.
These are not ABIs, better to be in original doc.
Better to describe drawer ABI, book ABIs are only available for s390 
in the ABI description.
...
diff --git a/Documentation/admin-guide/cputopology.rst
b/Documentation/admin-guide/cputopology.rst
index 4538d78..4672465 100644
--- a/Documentation/admin-guide/cputopology.rst
+++ b/Documentation/admin-guide/cputopology.rst
@@ -2,110 +2,6 @@
 How CPU topology info is exported via sysfs
 ===========================================
-Export CPU topology info via sysfs. Items (attributes) are similar
-to /proc/cpuinfo output of some architectures.  They reside in
-/sys/devices/system/cpu/cpuX/topology/:



-physical_package_id:


physical package id of cpuX. Typically corresponds to a physical
socket number, but the actual value is architecture and platform
dependent.


-die_id:


the CPU die ID of cpuX. Typically it is the hardware platform's
identifier (rather than the kernel's).  The actual value is
architecture and platform dependent.


-core_id:


the CPU core ID of cpuX. Typically it is the hardware platform's
identifier (rather than the kernel's).  The actual value is
architecture and platform dependent.


-book_id:


the book ID of cpuX. Typically it is the hardware platform's
identifier (rather than the kernel's).	The actual value is
architecture and platform dependent.


-drawer_id:


the drawer ID of cpuX. Typically it is the hardware platform's
identifier (rather than the kernel's).	The actual value is
architecture and platform dependent.


-core_cpus:


internal kernel map of CPUs within the same core.
(deprecated name: "thread_siblings")


-core_cpus_list:


human-readable list of CPUs within the same core.
The format is like 0-3, 8-11, 14,17. The maximum size is PAGE_SIZE,
so the tail of the string will be trimmed while its size is larger
than PAGE_SIZE.
(deprecated name: "thread_siblings_list");


-package_cpus:


internal kernel map of the CPUs sharing the same physical_package_id.
(deprecated name: "core_siblings")


-package_cpus_list:


human-readable list of CPUs sharing the same physical_package_id.
The format is like 0-3, 8-11, 14,17. The maximum size is PAGE_SIZE,
so the tail of the string will be trimmed while its size is larger
than PAGE_SIZE.
(deprecated name: "core_siblings_list")


-die_cpus:


internal kernel map of CPUs within the same die.


-die_cpus_list:


human-readable list of CPUs within the same die.
The format is like 0-3, 8-11, 14,17. The maximum size is PAGE_SIZE,
so the tail of the string will be trimmed while its size is larger
than PAGE_SIZE.


-book_siblings:


internal kernel map of cpuX's hardware threads within the same
book_id.


-book_siblings_list:


human-readable list of cpuX's hardware threads within the same
book_id.
The format is like 0-3, 8-11, 14,17. The maximum size is PAGE_SIZE,
so the tail of the string will be trimmed while its size is larger
than PAGE_SIZE.


-drawer_siblings:


internal kernel map of cpuX's hardware threads within the same
drawer_id.


-drawer_siblings_list:


human-readable list of cpuX's hardware threads within the same
drawer_id.
The format is like 0-3, 8-11, 14,17. The maximum size is PAGE_SIZE,
so the tail of the string will be trimmed while its size is larger
than PAGE_SIZE.


-Architecture-neutral, drivers/base/topology.c, exports these attributes.
-However, the book and drawer related sysfs files will only be created if
-CONFIG_SCHED_BOOK and CONFIG_SCHED_DRAWER are selected, respectively.



-CONFIG_SCHED_BOOK and CONFIG_SCHED_DRAWER are currently only used on s390,
-where they reflect the cpu and cache hierarchy.



For an architecture to support this feature, it must define some of
 these macros in include/asm-XXX/topology.h::
--
2.7.4

    