blob: d29cacc9b3c36bd2b5542eab53b00eedaa11f180 [file] [log] [blame]
Mauro Carvalho Chehabe8cb6f12017-05-14 09:52:01 -03001===========================================
2How CPU topology info is exported via sysfs
3===========================================
Zhang, Yanmin69dcc992006-02-03 03:04:36 -08004
Tian Tao05a463e2021-06-11 17:22:49 +12005CPU topology info is exported via sysfs. Items (attributes) are similar
6to /proc/cpuinfo output of some architectures. They reside in
7/sys/devices/system/cpu/cpuX/topology/. Please refer to the ABI file:
8Documentation/ABI/stable/sysfs-devices-system-cpu.
Heiko Carstensa62247e12016-05-21 11:10:13 +02009
Len Brown3a1c7792019-02-26 01:20:00 -050010Architecture-neutral, drivers/base/topology.c, exports these attributes.
Heiko Carstensf1045052021-11-29 14:03:09 +010011However the die, cluster, book, and drawer hierarchy related sysfs files will
12only be created if an architecture provides the related macros as described
13below.
Zhang, Yanmin69dcc992006-02-03 03:04:36 -080014
Ben Hutchingsc50cbb02008-06-04 21:47:29 -070015For an architecture to support this feature, it must define some of
Mauro Carvalho Chehabe8cb6f12017-05-14 09:52:01 -030016these macros in include/asm-XXX/topology.h::
Zhang, Yanmin69dcc992006-02-03 03:04:36 -080017
Mauro Carvalho Chehabe8cb6f12017-05-14 09:52:01 -030018 #define topology_physical_package_id(cpu)
Len Brown0e344d82019-05-13 13:58:47 -040019 #define topology_die_id(cpu)
Jonathan Cameronc5e22fe2021-09-24 20:51:02 +120020 #define topology_cluster_id(cpu)
Mauro Carvalho Chehabe8cb6f12017-05-14 09:52:01 -030021 #define topology_core_id(cpu)
22 #define topology_book_id(cpu)
23 #define topology_drawer_id(cpu)
24 #define topology_sibling_cpumask(cpu)
25 #define topology_core_cpumask(cpu)
Jonathan Cameronc5e22fe2021-09-24 20:51:02 +120026 #define topology_cluster_cpumask(cpu)
Len Brown2e4c54d2019-05-13 13:58:56 -040027 #define topology_die_cpumask(cpu)
Mauro Carvalho Chehabe8cb6f12017-05-14 09:52:01 -030028 #define topology_book_cpumask(cpu)
29 #define topology_drawer_cpumask(cpu)
30
31The type of ``**_id macros`` is int.
32The type of ``**_cpumask macros`` is ``(const) struct cpumask *``. The latter
33correspond with appropriate ``**_siblings`` sysfs attributes (except for
Bartosz Golaszewski54a53692015-05-26 15:11:29 +020034topology_sibling_cpumask() which corresponds with thread_siblings).
Zhang, Yanmin69dcc992006-02-03 03:04:36 -080035
Ben Hutchingsc50cbb02008-06-04 21:47:29 -070036To be consistent on all architectures, include/linux/topology.h
37provides default definitions for any of the above macros that are
38not defined by include/asm-XXX/topology.h:
Mauro Carvalho Chehabe8cb6f12017-05-14 09:52:01 -030039
Heiko Carstensaa483f32021-12-06 13:53:11 +0100401) topology_physical_package_id: -1
412) topology_die_id: -1
423) topology_cluster_id: -1
434) topology_core_id: 0
445) topology_book_id: -1
456) topology_drawer_id: -1
467) topology_sibling_cpumask: just the given CPU
478) topology_core_cpumask: just the given CPU
489) topology_cluster_cpumask: just the given CPU
Heiko Carstensf1045052021-11-29 14:03:09 +01004910) topology_die_cpumask: just the given CPU
5011) topology_book_cpumask: just the given CPU
5112) topology_drawer_cpumask: just the given CPU
Heiko Carstensb40d8ed2010-08-31 10:28:17 +020052
Alex Chiang663fb2f2009-10-21 21:45:31 -060053Additionally, CPU topology information is provided under
Mike Travisd62720a2008-12-17 14:14:30 -080054/sys/devices/system/cpu and includes these files. The internal
55source for the output is in brackets ("[]").
56
Mauro Carvalho Chehabe8cb6f12017-05-14 09:52:01 -030057 =========== ==========================================================
Alex Chiang663fb2f2009-10-21 21:45:31 -060058 kernel_max: the maximum CPU index allowed by the kernel configuration.
Mike Travisd62720a2008-12-17 14:14:30 -080059 [NR_CPUS-1]
60
Alex Chiang663fb2f2009-10-21 21:45:31 -060061 offline: CPUs that are not online because they have been
Yang Xud5caec32021-06-23 09:37:48 +080062 HOTPLUGGED off or exceed the limit of CPUs allowed by the
63 kernel configuration (kernel_max above).
64 [~cpu_online_mask + cpus >= NR_CPUS]
Mike Travisd62720a2008-12-17 14:14:30 -080065
Alex Chiang663fb2f2009-10-21 21:45:31 -060066 online: CPUs that are online and being scheduled [cpu_online_mask]
Mike Travisd62720a2008-12-17 14:14:30 -080067
Alex Chiang663fb2f2009-10-21 21:45:31 -060068 possible: CPUs that have been allocated resources and can be
Mike Travisd62720a2008-12-17 14:14:30 -080069 brought online if they are present. [cpu_possible_mask]
70
Alex Chiang663fb2f2009-10-21 21:45:31 -060071 present: CPUs that have been identified as being present in the
Mike Travisd62720a2008-12-17 14:14:30 -080072 system. [cpu_present_mask]
Mauro Carvalho Chehabe8cb6f12017-05-14 09:52:01 -030073 =========== ==========================================================
Mike Travisd62720a2008-12-17 14:14:30 -080074
75The format for the above output is compatible with cpulist_parse()
76[see <linux/cpumask.h>]. Some examples follow.
77
Alex Chiang663fb2f2009-10-21 21:45:31 -060078In this example, there are 64 CPUs in the system but cpus 32-63 exceed
Mike Travisd62720a2008-12-17 14:14:30 -080079the kernel max which is limited to 0..31 by the NR_CPUS config option
Alex Chiang663fb2f2009-10-21 21:45:31 -060080being 32. Note also that CPUs 2 and 4-31 are not online but could be
Mauro Carvalho Chehabe8cb6f12017-05-14 09:52:01 -030081brought online as they are both present and possible::
Mike Travisd62720a2008-12-17 14:14:30 -080082
83 kernel_max: 31
84 offline: 2,4-31,32-63
85 online: 0-1,3
86 possible: 0-31
87 present: 0-31
88
89In this example, the NR_CPUS config option is 128, but the kernel was
Alex Chiang663fb2f2009-10-21 21:45:31 -060090started with possible_cpus=144. There are 4 CPUs in the system and cpu2
91was manually taken offline (and is the only CPU that can be brought
Mauro Carvalho Chehabe8cb6f12017-05-14 09:52:01 -030092online.)::
Mike Travisd62720a2008-12-17 14:14:30 -080093
94 kernel_max: 127
95 offline: 2,4-127,128-143
96 online: 0-1,3
97 possible: 0-127
98 present: 0-3
99
Yang Xud5caec32021-06-23 09:37:48 +0800100See Documentation/core-api/cpu_hotplug.rst for the possible_cpus=NUM
101kernel start parameter as well as more information on the various cpumasks.