1===========================================
2How CPU topology info is exported via sysfs
3===========================================
4
5Export CPU topology info via sysfs. Items (attributes) are similar
6to /proc/cpuinfo output of some architectures:
7
81) /sys/devices/system/cpu/cpuX/topology/physical_package_id:
9
10	physical package id of cpuX. Typically corresponds to a physical
11	socket number, but the actual value is architecture and platform
12	dependent.
13
142) /sys/devices/system/cpu/cpuX/topology/core_id:
15
16	the CPU core ID of cpuX. Typically it is the hardware platform's
17	identifier (rather than the kernel's).  The actual value is
18	architecture and platform dependent.
19
203) /sys/devices/system/cpu/cpuX/topology/book_id:
21
22	the book ID of cpuX. Typically it is the hardware platform's
23	identifier (rather than the kernel's).	The actual value is
24	architecture and platform dependent.
25
264) /sys/devices/system/cpu/cpuX/topology/drawer_id:
27
28	the drawer ID of cpuX. Typically it is the hardware platform's
29	identifier (rather than the kernel's).	The actual value is
30	architecture and platform dependent.
31
325) /sys/devices/system/cpu/cpuX/topology/thread_siblings:
33
34	internal kernel map of cpuX's hardware threads within the same
35	core as cpuX.
36
376) /sys/devices/system/cpu/cpuX/topology/thread_siblings_list:
38
39	human-readable list of cpuX's hardware threads within the same
40	core as cpuX.
41
427) /sys/devices/system/cpu/cpuX/topology/core_siblings:
43
44	internal kernel map of cpuX's hardware threads within the same
45	physical_package_id.
46
478) /sys/devices/system/cpu/cpuX/topology/core_siblings_list:
48
49	human-readable list of cpuX's hardware threads within the same
50	physical_package_id.
51
529) /sys/devices/system/cpu/cpuX/topology/book_siblings:
53
54	internal kernel map of cpuX's hardware threads within the same
55	book_id.
56
5710) /sys/devices/system/cpu/cpuX/topology/book_siblings_list:
58
59	human-readable list of cpuX's hardware threads within the same
60	book_id.
61
6211) /sys/devices/system/cpu/cpuX/topology/drawer_siblings:
63
64	internal kernel map of cpuX's hardware threads within the same
65	drawer_id.
66
6712) /sys/devices/system/cpu/cpuX/topology/drawer_siblings_list:
68
69	human-readable list of cpuX's hardware threads within the same
70	drawer_id.
71
72To implement it in an architecture-neutral way, a new source file,
73drivers/base/topology.c, is to export the 6 to 12 attributes. The book
74and drawer related sysfs files will only be created if CONFIG_SCHED_BOOK
75and CONFIG_SCHED_DRAWER are selected.
76
77CONFIG_SCHED_BOOK and CONFIG_DRAWER are currently only used on s390, where
78they reflect the cpu and cache hierarchy.
79
80For an architecture to support this feature, it must define some of
81these macros in include/asm-XXX/topology.h::
82
83	#define topology_physical_package_id(cpu)
84	#define topology_core_id(cpu)
85	#define topology_book_id(cpu)
86	#define topology_drawer_id(cpu)
87	#define topology_sibling_cpumask(cpu)
88	#define topology_core_cpumask(cpu)
89	#define topology_book_cpumask(cpu)
90	#define topology_drawer_cpumask(cpu)
91
92The type of ``**_id macros`` is int.
93The type of ``**_cpumask macros`` is ``(const) struct cpumask *``. The latter
94correspond with appropriate ``**_siblings`` sysfs attributes (except for
95topology_sibling_cpumask() which corresponds with thread_siblings).
96
97To be consistent on all architectures, include/linux/topology.h
98provides default definitions for any of the above macros that are
99not defined by include/asm-XXX/topology.h:
100
1011) physical_package_id: -1
1022) core_id: 0
1033) sibling_cpumask: just the given CPU
1044) core_cpumask: just the given CPU
105
106For architectures that don't support books (CONFIG_SCHED_BOOK) there are no
107default definitions for topology_book_id() and topology_book_cpumask().
108For architectures that don't support drawers (CONFIG_SCHED_DRAWER) there are
109no default definitions for topology_drawer_id() and topology_drawer_cpumask().
110
111Additionally, CPU topology information is provided under
112/sys/devices/system/cpu and includes these files.  The internal
113source for the output is in brackets ("[]").
114
115    =========== ==========================================================
116    kernel_max: the maximum CPU index allowed by the kernel configuration.
117		[NR_CPUS-1]
118
119    offline:	CPUs that are not online because they have been
120		HOTPLUGGED off (see cpu-hotplug.txt) or exceed the limit
121		of CPUs allowed by the kernel configuration (kernel_max
122		above). [~cpu_online_mask + cpus >= NR_CPUS]
123
124    online:	CPUs that are online and being scheduled [cpu_online_mask]
125
126    possible:	CPUs that have been allocated resources and can be
127		brought online if they are present. [cpu_possible_mask]
128
129    present:	CPUs that have been identified as being present in the
130		system. [cpu_present_mask]
131    =========== ==========================================================
132
133The format for the above output is compatible with cpulist_parse()
134[see <linux/cpumask.h>].  Some examples follow.
135
136In this example, there are 64 CPUs in the system but cpus 32-63 exceed
137the kernel max which is limited to 0..31 by the NR_CPUS config option
138being 32.  Note also that CPUs 2 and 4-31 are not online but could be
139brought online as they are both present and possible::
140
141     kernel_max: 31
142        offline: 2,4-31,32-63
143         online: 0-1,3
144       possible: 0-31
145        present: 0-31
146
147In this example, the NR_CPUS config option is 128, but the kernel was
148started with possible_cpus=144.  There are 4 CPUs in the system and cpu2
149was manually taken offline (and is the only CPU that can be brought
150online.)::
151
152     kernel_max: 127
153        offline: 2,4-127,128-143
154         online: 0-1,3
155       possible: 0-127
156        present: 0-3
157
158See cpu-hotplug.txt for the possible_cpus=NUM kernel start parameter
159as well as more information on the various cpumasks.
160