Mauro Carvalho Chehab | e8cb6f1 | 2017-05-14 09:52:01 -0300 | [diff] [blame] | 1 | =========================================== |
| 2 | How CPU topology info is exported via sysfs |
| 3 | =========================================== |
Zhang, Yanmin | 69dcc99 | 2006-02-03 03:04:36 -0800 | [diff] [blame] | 4 | |
Tian Tao | 05a463e | 2021-06-11 17:22:49 +1200 | [diff] [blame] | 5 | CPU topology info is exported via sysfs. Items (attributes) are similar |
| 6 | to /proc/cpuinfo output of some architectures. They reside in |
| 7 | /sys/devices/system/cpu/cpuX/topology/. Please refer to the ABI file: |
| 8 | Documentation/ABI/stable/sysfs-devices-system-cpu. |
Heiko Carstens | a62247e1 | 2016-05-21 11:10:13 +0200 | [diff] [blame] | 9 | |
Len Brown | 3a1c779 | 2019-02-26 01:20:00 -0500 | [diff] [blame] | 10 | Architecture-neutral, drivers/base/topology.c, exports these attributes. |
Heiko Carstens | f104505 | 2021-11-29 14:03:09 +0100 | [diff] [blame] | 11 | However the die, cluster, book, and drawer hierarchy related sysfs files will |
| 12 | only be created if an architecture provides the related macros as described |
| 13 | below. |
Zhang, Yanmin | 69dcc99 | 2006-02-03 03:04:36 -0800 | [diff] [blame] | 14 | |
Ben Hutchings | c50cbb0 | 2008-06-04 21:47:29 -0700 | [diff] [blame] | 15 | For an architecture to support this feature, it must define some of |
Mauro Carvalho Chehab | e8cb6f1 | 2017-05-14 09:52:01 -0300 | [diff] [blame] | 16 | these macros in include/asm-XXX/topology.h:: |
Zhang, Yanmin | 69dcc99 | 2006-02-03 03:04:36 -0800 | [diff] [blame] | 17 | |
Mauro Carvalho Chehab | e8cb6f1 | 2017-05-14 09:52:01 -0300 | [diff] [blame] | 18 | #define topology_physical_package_id(cpu) |
Len Brown | 0e344d8 | 2019-05-13 13:58:47 -0400 | [diff] [blame] | 19 | #define topology_die_id(cpu) |
Jonathan Cameron | c5e22fe | 2021-09-24 20:51:02 +1200 | [diff] [blame] | 20 | #define topology_cluster_id(cpu) |
Mauro Carvalho Chehab | e8cb6f1 | 2017-05-14 09:52:01 -0300 | [diff] [blame] | 21 | #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 Cameron | c5e22fe | 2021-09-24 20:51:02 +1200 | [diff] [blame] | 26 | #define topology_cluster_cpumask(cpu) |
Len Brown | 2e4c54d | 2019-05-13 13:58:56 -0400 | [diff] [blame] | 27 | #define topology_die_cpumask(cpu) |
Mauro Carvalho Chehab | e8cb6f1 | 2017-05-14 09:52:01 -0300 | [diff] [blame] | 28 | #define topology_book_cpumask(cpu) |
| 29 | #define topology_drawer_cpumask(cpu) |
| 30 | |
| 31 | The type of ``**_id macros`` is int. |
| 32 | The type of ``**_cpumask macros`` is ``(const) struct cpumask *``. The latter |
| 33 | correspond with appropriate ``**_siblings`` sysfs attributes (except for |
Bartosz Golaszewski | 54a5369 | 2015-05-26 15:11:29 +0200 | [diff] [blame] | 34 | topology_sibling_cpumask() which corresponds with thread_siblings). |
Zhang, Yanmin | 69dcc99 | 2006-02-03 03:04:36 -0800 | [diff] [blame] | 35 | |
Ben Hutchings | c50cbb0 | 2008-06-04 21:47:29 -0700 | [diff] [blame] | 36 | To be consistent on all architectures, include/linux/topology.h |
| 37 | provides default definitions for any of the above macros that are |
| 38 | not defined by include/asm-XXX/topology.h: |
Mauro Carvalho Chehab | e8cb6f1 | 2017-05-14 09:52:01 -0300 | [diff] [blame] | 39 | |
Heiko Carstens | aa483f3 | 2021-12-06 13:53:11 +0100 | [diff] [blame] | 40 | 1) topology_physical_package_id: -1 |
| 41 | 2) topology_die_id: -1 |
| 42 | 3) topology_cluster_id: -1 |
| 43 | 4) topology_core_id: 0 |
| 44 | 5) topology_book_id: -1 |
| 45 | 6) topology_drawer_id: -1 |
| 46 | 7) topology_sibling_cpumask: just the given CPU |
| 47 | 8) topology_core_cpumask: just the given CPU |
| 48 | 9) topology_cluster_cpumask: just the given CPU |
Heiko Carstens | f104505 | 2021-11-29 14:03:09 +0100 | [diff] [blame] | 49 | 10) topology_die_cpumask: just the given CPU |
| 50 | 11) topology_book_cpumask: just the given CPU |
| 51 | 12) topology_drawer_cpumask: just the given CPU |
Heiko Carstens | b40d8ed | 2010-08-31 10:28:17 +0200 | [diff] [blame] | 52 | |
Alex Chiang | 663fb2f | 2009-10-21 21:45:31 -0600 | [diff] [blame] | 53 | Additionally, CPU topology information is provided under |
Mike Travis | d62720a | 2008-12-17 14:14:30 -0800 | [diff] [blame] | 54 | /sys/devices/system/cpu and includes these files. The internal |
| 55 | source for the output is in brackets ("[]"). |
| 56 | |
Mauro Carvalho Chehab | e8cb6f1 | 2017-05-14 09:52:01 -0300 | [diff] [blame] | 57 | =========== ========================================================== |
Alex Chiang | 663fb2f | 2009-10-21 21:45:31 -0600 | [diff] [blame] | 58 | kernel_max: the maximum CPU index allowed by the kernel configuration. |
Mike Travis | d62720a | 2008-12-17 14:14:30 -0800 | [diff] [blame] | 59 | [NR_CPUS-1] |
| 60 | |
Alex Chiang | 663fb2f | 2009-10-21 21:45:31 -0600 | [diff] [blame] | 61 | offline: CPUs that are not online because they have been |
Yang Xu | d5caec3 | 2021-06-23 09:37:48 +0800 | [diff] [blame] | 62 | 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 Travis | d62720a | 2008-12-17 14:14:30 -0800 | [diff] [blame] | 65 | |
Alex Chiang | 663fb2f | 2009-10-21 21:45:31 -0600 | [diff] [blame] | 66 | online: CPUs that are online and being scheduled [cpu_online_mask] |
Mike Travis | d62720a | 2008-12-17 14:14:30 -0800 | [diff] [blame] | 67 | |
Alex Chiang | 663fb2f | 2009-10-21 21:45:31 -0600 | [diff] [blame] | 68 | possible: CPUs that have been allocated resources and can be |
Mike Travis | d62720a | 2008-12-17 14:14:30 -0800 | [diff] [blame] | 69 | brought online if they are present. [cpu_possible_mask] |
| 70 | |
Alex Chiang | 663fb2f | 2009-10-21 21:45:31 -0600 | [diff] [blame] | 71 | present: CPUs that have been identified as being present in the |
Mike Travis | d62720a | 2008-12-17 14:14:30 -0800 | [diff] [blame] | 72 | system. [cpu_present_mask] |
Mauro Carvalho Chehab | e8cb6f1 | 2017-05-14 09:52:01 -0300 | [diff] [blame] | 73 | =========== ========================================================== |
Mike Travis | d62720a | 2008-12-17 14:14:30 -0800 | [diff] [blame] | 74 | |
| 75 | The format for the above output is compatible with cpulist_parse() |
| 76 | [see <linux/cpumask.h>]. Some examples follow. |
| 77 | |
Alex Chiang | 663fb2f | 2009-10-21 21:45:31 -0600 | [diff] [blame] | 78 | In this example, there are 64 CPUs in the system but cpus 32-63 exceed |
Mike Travis | d62720a | 2008-12-17 14:14:30 -0800 | [diff] [blame] | 79 | the kernel max which is limited to 0..31 by the NR_CPUS config option |
Alex Chiang | 663fb2f | 2009-10-21 21:45:31 -0600 | [diff] [blame] | 80 | being 32. Note also that CPUs 2 and 4-31 are not online but could be |
Mauro Carvalho Chehab | e8cb6f1 | 2017-05-14 09:52:01 -0300 | [diff] [blame] | 81 | brought online as they are both present and possible:: |
Mike Travis | d62720a | 2008-12-17 14:14:30 -0800 | [diff] [blame] | 82 | |
| 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 | |
| 89 | In this example, the NR_CPUS config option is 128, but the kernel was |
Alex Chiang | 663fb2f | 2009-10-21 21:45:31 -0600 | [diff] [blame] | 90 | started with possible_cpus=144. There are 4 CPUs in the system and cpu2 |
| 91 | was manually taken offline (and is the only CPU that can be brought |
Mauro Carvalho Chehab | e8cb6f1 | 2017-05-14 09:52:01 -0300 | [diff] [blame] | 92 | online.):: |
Mike Travis | d62720a | 2008-12-17 14:14:30 -0800 | [diff] [blame] | 93 | |
| 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 Xu | d5caec3 | 2021-06-23 09:37:48 +0800 | [diff] [blame] | 100 | See Documentation/core-api/cpu_hotplug.rst for the possible_cpus=NUM |
| 101 | kernel start parameter as well as more information on the various cpumasks. |