0001 .. SPDX-License-Identifier: GPL-2.0
0002 .. include:: ../disclaimer-zh_CN.rst
0003
0004 :Original: Documentation/admin-guide/cputopology.rst
0005
0006 :翻译:
0007
0008 唐艺舟 Tang Yizhou <tangyeechou@gmail.com>
0009
0010 ==========================
0011 如何通过sysfs将CPU拓扑导出
0012 ==========================
0013
0014 CPU拓扑信息通过sysfs导出。显示的项（属性）和某些架构的/proc/cpuinfo输出相似。它们位于
0015 /sys/devices/system/cpu/cpuX/topology/。请阅读ABI文件：
0016 Documentation/ABI/stable/sysfs-devices-system-cpu。
0017
0018 drivers/base/topology.c是体系结构中性的，它导出了这些属性。然而，die、cluster、book、
0019 draw这些层次结构相关的文件仅在体系结构提供了下文描述的宏的条件下被创建。
0020
0021 对于支持这个特性的体系结构，它必须在include/asm-XXX/topology.h中定义这些宏中的一部分::
0022
0023 #define topology_physical_package_id(cpu)
0024 #define topology_die_id(cpu)
0025 #define topology_cluster_id(cpu)
0026 #define topology_core_id(cpu)
0027 #define topology_book_id(cpu)
0028 #define topology_drawer_id(cpu)
0029 #define topology_sibling_cpumask(cpu)
0030 #define topology_core_cpumask(cpu)
0031 #define topology_cluster_cpumask(cpu)
0032 #define topology_die_cpumask(cpu)
0033 #define topology_book_cpumask(cpu)
0034 #define topology_drawer_cpumask(cpu)
0035
0036 ``**_id macros`` 的类型是int。
0037 ``**_cpumask macros`` 的类型是 ``(const) struct cpumask *`` 。后者和恰当的
0038 ``**_siblings`` sysfs属性对应（除了topology_sibling_cpumask()，它和thread_siblings
0039 对应）。
0040
0041 为了在所有体系结构上保持一致，include/linux/topology.h提供了上述所有宏的默认定义，以防
0042 它们未在include/asm-XXX/topology.h中定义:
0043
0044 1) topology_physical_package_id: -1
0045 2) topology_die_id: -1
0046 3) topology_cluster_id: -1
0047 4) topology_core_id: 0
0048 5) topology_book_id: -1
0049 6) topology_drawer_id: -1
0050 7) topology_sibling_cpumask: 仅入参CPU
0051 8) topology_core_cpumask: 仅入参CPU
0052 9) topology_cluster_cpumask: 仅入参CPU
0053 10) topology_die_cpumask: 仅入参CPU
0054 11) topology_book_cpumask: 仅入参CPU
0055 12) topology_drawer_cpumask: 仅入参CPU
0056
0057 此外，CPU拓扑信息由/sys/devices/system/cpu提供，包含下述文件。输出对应的内部数据源放在
0058 方括号（"[]"）中。
0059
0060 =========== ==================================================================
0061 kernel_max: 内核配置允许的最大CPU下标值。[NR_CPUS-1]
0062
0063 offline: 由于热插拔移除或者超过内核允许的CPU上限（上文描述的kernel_max）
0064 导致未上线的CPU。[~cpu_online_mask + cpus >= NR_CPUS]
0065
0066 online: 在线的CPU，可供调度使用。[cpu_online_mask]
0067
0068 possible: 已被分配资源的CPU，如果它们CPU实际存在，可以上线。
0069 [cpu_possible_mask]
0070
0071 present: 被系统识别实际存在的CPU。[cpu_present_mask]
0072 =========== ==================================================================
0073
0074 上述输出的格式和cpulist_parse()兼容[参见 <linux/cpumask.h>]。下面给些例子。
0075
0076 在本例中，系统中有64个CPU，但是CPU 32-63超过了kernel_max值，因为NR_CPUS配置项是32，
0077 取值范围被限制为0..31。此外注意CPU2和4-31未上线，但是可以上线，因为它们同时存在于
0078 present和possible::
0079
0080 kernel_max: 31
0081 offline: 2,4-31,32-63
0082 online: 0-1,3
0083 possible: 0-31
0084 present: 0-31
0085
0086 在本例中，NR_CPUS配置项是128，但内核启动时设置possible_cpus=144。系统中有4个CPU，
0087 CPU2被手动设置下线（也是唯一一个可以上线的CPU）::
0088
0089 kernel_max: 127
0090 offline: 2,4-127,128-143
0091 online: 0-1,3
0092 possible: 0-127
0093 present: 0-3
0094
0095 阅读Documentation/core-api/cpu_hotplug.rst可了解开机参数possible_cpus=NUM，同时还
0096 可以了解各种cpumask的信息。
