0001 ===========================================
0002 How CPU topology info is exported via sysfs
0003 ===========================================
0004
0005 CPU topology info is exported via sysfs. Items (attributes) are similar
0006 to /proc/cpuinfo output of some architectures. They reside in
0007 /sys/devices/system/cpu/cpuX/topology/. Please refer to the ABI file:
0008 Documentation/ABI/stable/sysfs-devices-system-cpu.
0009
0010 Architecture-neutral, drivers/base/topology.c, exports these attributes.
0011 However the die, cluster, book, and drawer hierarchy related sysfs files will
0012 only be created if an architecture provides the related macros as described
0013 below.
0014
0015 For an architecture to support this feature, it must define some of
0016 these macros in include/asm-XXX/topology.h::
0017
0018 #define topology_physical_package_id(cpu)
0019 #define topology_die_id(cpu)
0020 #define topology_cluster_id(cpu)
0021 #define topology_core_id(cpu)
0022 #define topology_book_id(cpu)
0023 #define topology_drawer_id(cpu)
0024 #define topology_sibling_cpumask(cpu)
0025 #define topology_core_cpumask(cpu)
0026 #define topology_cluster_cpumask(cpu)
0027 #define topology_die_cpumask(cpu)
0028 #define topology_book_cpumask(cpu)
0029 #define topology_drawer_cpumask(cpu)
0030
0031 The type of ``**_id macros`` is int.
0032 The type of ``**_cpumask macros`` is ``(const) struct cpumask *``. The latter
0033 correspond with appropriate ``**_siblings`` sysfs attributes (except for
0034 topology_sibling_cpumask() which corresponds with thread_siblings).
0035
0036 To be consistent on all architectures, include/linux/topology.h
0037 provides default definitions for any of the above macros that are
0038 not defined by include/asm-XXX/topology.h:
0039
0040 1) topology_physical_package_id: -1
0041 2) topology_die_id: -1
0042 3) topology_cluster_id: -1
0043 4) topology_core_id: 0
0044 5) topology_book_id: -1
0045 6) topology_drawer_id: -1
0046 7) topology_sibling_cpumask: just the given CPU
0047 8) topology_core_cpumask: just the given CPU
0048 9) topology_cluster_cpumask: just the given CPU
0049 10) topology_die_cpumask: just the given CPU
0050 11) topology_book_cpumask: just the given CPU
0051 12) topology_drawer_cpumask: just the given CPU
0052
0053 Additionally, CPU topology information is provided under
0054 /sys/devices/system/cpu and includes these files. The internal
0055 source for the output is in brackets ("[]").
0056
0057 =========== ==========================================================
0058 kernel_max: the maximum CPU index allowed by the kernel configuration.
0059 [NR_CPUS-1]
0060
0061 offline: CPUs that are not online because they have been
0062 HOTPLUGGED off or exceed the limit of CPUs allowed by the
0063 kernel configuration (kernel_max above).
0064 [~cpu_online_mask + cpus >= NR_CPUS]
0065
0066 online: CPUs that are online and being scheduled [cpu_online_mask]
0067
0068 possible: CPUs that have been allocated resources and can be
0069 brought online if they are present. [cpu_possible_mask]
0070
0071 present: CPUs that have been identified as being present in the
0072 system. [cpu_present_mask]
0073 =========== ==========================================================
0074
0075 The format for the above output is compatible with cpulist_parse()
0076 [see <linux/cpumask.h>]. Some examples follow.
0077
0078 In this example, there are 64 CPUs in the system but cpus 32-63 exceed
0079 the kernel max which is limited to 0..31 by the NR_CPUS config option
0080 being 32. Note also that CPUs 2 and 4-31 are not online but could be
0081 brought online as they are both present and possible::
0082
0083 kernel_max: 31
0084 offline: 2,4-31,32-63
0085 online: 0-1,3
0086 possible: 0-31
0087 present: 0-31
0088
0089 In this example, the NR_CPUS config option is 128, but the kernel was
0090 started with possible_cpus=144. There are 4 CPUs in the system and cpu2
0091 was manually taken offline (and is the only CPU that can be brought
0092 online.)::
0093
0094 kernel_max: 127
0095 offline: 2,4-127,128-143
0096 online: 0-1,3
0097 possible: 0-127
0098 present: 0-3
0099
0100 See Documentation/core-api/cpu_hotplug.rst for the possible_cpus=NUM
0101 kernel start parameter as well as more information on the various cpumasks.
