Documentation/admin-guide/cputopology.rst

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