-----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