简介本资源是Hardware Localityhwloc开源项目的完整C语言源码包面向HPC开发者、系统编程学习者及需深度优化多核/NUMA架构下代码局部性的中高级C程序员。hwloc提供统一接口发现CPU拓扑、内存层级、PCI设备与缓存关联关系支撑进程绑定、内存分配策略与性能调优等关键场景。压缩包共793个文件涵盖143个C源码核心逻辑与工具实现、90个头文件API定义、63个XML拓扑描述样本、31个构建脚本autotools相关及21个Shell工具封装辅以文档、测试输出与跨平台工程文件vcxproj/sln总大小3.41MB结构完整、开箱即用。目前已有211人学习下载读者可直接编译运行lstopo、hwloc-bind、hwloc-info等命令行工具深入理解硬件拓扑建模原理并基于C API开发定制化资源调度模块。1. 用 hwloc 探测真实物理拓扑不是查 CPU 核数那么简单很多人写 C 程序时调sysconf(_SC_NPROCESSORS_ONLN)就以为拿到了“可用核数”结果在 NUMA 服务器上跑多线程性能抖动、内存带宽不均、绑核失效——根本原因是操作系统报告的逻辑 CPU 列表和硬件真实的层级关系Socket → Core → L2 Cache → PU完全脱节。hwlocHierarchical Workload Locality正是为解决这个问题而生它不依赖内核抽象而是通过读取 ACPI 表、x86 CPUID、PCIe 配置空间、Linux sysfs 等底层信息重建出从芯片封装到缓存行粒度的完整硬件拓扑图。你写的 C 程序若需做 NUMA 感知内存分配、线程亲和性绑定、GPU 与 CPU 的 PCIe 距离判断或容器运行时限制跨 socket 访存hwloc 就是不可绕过的基础设施。本文面向已能编译 C 程序、熟悉make和gcc -I的开发者不讲 API 文档搬运只聚焦「怎么把 hwloc 嵌入你的项目」「为什么必须用hwloc_topology_load()而非直接malloc」「如何避免hwloc_get_obj_by_type()返回 NULL 的静默失败」——所有代码均可在 Ubuntu 22.04 / CentOS 8 / WSL2 的 GCC 11 环境下一键复现。2. 编译与链接 hwloc静态库 vs pkg-config 的实际取舍2.1 从源码构建是唯一可控路径hwloc 官方不提供 Windows 二进制包Linux 发行版仓库中的版本常滞后 2–3 年如 CentOS 8 默认 hwloc-1.11而当前稳定版为 2.9.0且默认关闭 PCI 设备发现和 OpenCL 支持。因此生产环境必须源码编译# 下载最新稳定版截至 2024 年中为 2.9.0 wget https://download.open-mpi.org/release/hwloc/v2.9/hwloc-2.9.0.tar.gz tar -xzf hwloc-2.9.0.tar.gz cd hwloc-2.9.0 # 关键配置启用 PCI 扫描用于 GPU/NVMe 距离计算、禁用 Python 绑定C 项目无需 ./configure --prefix/usr/local/hwloc-2.9.0 \ --enable-pci \ --disable-python \ --disable-libxml2 \ --without-x make -j$(nproc) sudo make install提示--without-x可跳过 X11 依赖避免在 headless 服务器上因缺少libX11-dev中断构建--disable-libxml2是因 hwloc 仅用 libxml2 解析 XML 导出文件纯 C 调用场景下可安全禁用。2.2 头文件与库路径的硬编码陷阱安装后头文件位于/usr/local/hwloc-2.9.0/include/hwloc/但直接#include hwloc.h会失败——因为hwloc.h内部包含#include hwloc/bitmap.h等相对路径。正确做法是// main.c #include hwloc.h #include hwloc/plugins.h // 若需自定义插件如解析自定义拓扑文件 #include stdio.h int main() { hwloc_topology_t topology; hwloc_topology_init(topology); hwloc_topology_load(topology); // 必须调用否则所有查询返回空 // ... 后续操作 }编译命令必须显式指定头文件和库路径gcc -I/usr/local/hwloc-2.9.0/include \ -L/usr/local/hwloc-2.9.0/lib \ -lhwloc \ -o detect_topology main.c注意-lhwloc必须放在.c文件之后否则链接器找不到未解析的符号若使用pkg-config需先运行export PKG_CONFIG_PATH/usr/local/hwloc-2.9.0/lib/pkgconfig则可用pkg-config --cflags --libs hwloc生成参数但该方式在交叉编译或多版本共存时易出错我一般在 Makefile 中硬编码路径以保确定性。2.3 验证安装是否生效的最小可执行测试写一个 15 行的验证程序不依赖任何外部逻辑只检查拓扑加载和对象计数// verify.c #include hwloc.h #include stdio.h int main() { hwloc_topology_t topo; hwloc_topology_init(topo); if (hwloc_topology_load(topo) 0) { fprintf(stderr, hwloc_topology_load failed\n); return 1; } int nbsockets hwloc_get_nbobjs_by_type(topo, HWLOC_OBJ_SOCKET); int nbcores hwloc_get_nbobjs_by_type(topo, HWLOC_OBJ_CORE); printf(Sockets: %d, Cores: %d\n, nbsockets, nbcores); hwloc_topology_destroy(topo); return 0; }编译并运行gcc -I/usr/local/hwloc-2.9.0/include -L/usr/local/hwloc-2.9.0/lib -lhwloc verify.c -o verify ./verify # 正常输出类似Sockets: 2, Cores: 64若报undefined reference to hwloc_topology_init说明-lhwloc位置错误若输出Sockets: 0说明hwloc_topology_load()未被调用或权限不足需 root 运行某些探测。3. 用 C 代码精准获取 NUMA 节点与 CPU 绑定关系3.1 为什么hwloc_get_obj_by_type()不能直接遍历所有对象初学者常写// ❌ 错误示范假设 HWLOC_OBJ_CORE 总是连续编号 for (int i 0; i hwloc_get_nbobjs_by_type(topo, HWLOC_OBJ_CORE); i) { hwloc_obj_t core hwloc_get_obj_by_type(topo, HWLOC_OBJ_CORE, i); // core 可能为 NULL因为索引 i 对应的是“第 i 个 CORE 对象”但对象在拓扑树中可能有空洞 }hwloc 的对象索引不是数组下标而是拓扑树中同类型对象的全局序号。正确遍历必须用hwloc_get_next_obj_by_type()// ✅ 正确遍历所有 CORE 对象 hwloc_obj_t obj NULL; while ((obj hwloc_get_next_obj_by_type(topo, HWLOC_OBJ_CORE, obj)) ! NULL) { printf(Core %u on NUMA node %d, logical index: %u\n, obj-logical_index, obj-nodeset ? hwloc_bitmap_first(obj-nodeset) : -1, obj-os_index); }3.2 获取 CPU 与 NUMA 节点的映射表关键生产级代码以下函数生成cpu_to_numa[cpu_id] numa_id数组用于后续numa_alloc_onnode()分配#include hwloc.h #include stdlib.h #include assert.h int* build_cpu_to_numa_map(hwloc_topology_t topo, int* max_cpu_id) { // 第一步找出最大 OS CPU ID即 /proc/cpuinfo 中的 processor 字段最大值 hwloc_obj_t root hwloc_get_root_obj(topo); *max_cpu_id -1; hwloc_obj_t pu; hwloc_obj_t next_pu NULL; while ((pu hwloc_get_next_obj_by_type(topo, HWLOC_OBJ_PU, next_pu)) ! NULL) { if (pu-os_index *max_cpu_id) *max_cpu_id pu-os_index; next_pu pu; } assert(*max_cpu_id 0); // 第二步分配映射数组初始化为 -1表示未映射 int* map calloc((*max_cpu_id) 1, sizeof(int)); if (!map) return NULL; // 第三步对每个 NUMA 节点遍历其子 PU 并填表 hwloc_obj_t node; hwloc_obj_t next_node NULL; while ((node hwloc_get_next_obj_by_type(topo, HWLOC_OBJ_NODE, next_node)) ! NULL) { if (!node-cpuset) continue; // 某些节点可能无 CPU 关联 hwloc_bitmap_foreach_begin(i, node-cpuset) { if (i *max_cpu_id) { map[i] node-logical_index; } } hwloc_bitmap_foreach_end(); next_node node; } return map; } // 使用示例 int main() { hwloc_topology_t topo; hwloc_topology_init(topo); hwloc_topology_load(topo); int max_cpu_id; int* cpu_to_numa build_cpu_to_numa_map(topo, max_cpu_id); if (!cpu_to_numa) { fprintf(stderr, Failed to build CPU-NUMA map\n); return 1; } // 打印前 8 个 CPU 的映射 for (int i 0; i 8 i max_cpu_id; i) { printf(CPU %d - NUMA node %d\n, i, cpu_to_numa[i]); } free(cpu_to_numa); hwloc_topology_destroy(topo); return 0; }参数说明pu-os_index是操作系统看到的逻辑 CPU ID对应sched_setaffinity()的cpu_set_t位图索引node-logical_index是 hwloc 分配的 NUMA 节点序号从 0 开始与numactl --hardware输出的node 0一致node-cpuset是该 NUMA 节点覆盖的所有 CPU 位图hwloc_bitmap_foreach_begin/end是安全遍历位图的标准宏。3.3 绑定线程到特定 NUMA 节点的完整流程单纯pthread_setaffinity_np()只能绑 CPU要实现“绑 CPU 且分配本地内存”需组合调用#include pthread.h #include numa.h // 需链接 -lnuma void bind_thread_to_numa_node(pthread_t thread, int numa_node_id) { // 步骤 1获取该 NUMA 节点的所有 CPU cpu_set_t cpuset; CPU_ZERO(cpuset); hwloc_topology_t topo; hwloc_topology_init(topo); hwloc_topology_load(topo); hwloc_obj_t node hwloc_get_obj_by_type(topo, HWLOC_OBJ_NODE, numa_node_id); if (node node-cpuset) { hwloc_bitmap_foreach_begin(i, node-cpuset) { CPU_SET(i, cpuset); } hwloc_bitmap_foreach_end(); } hwloc_topology_destroy(topo); // 步骤 2设置线程 CPU 亲和性 pthread_setaffinity_np(thread, sizeof(cpuset), cpuset); // 步骤 3设置线程 NUMA 策略分配内存时优先本节点 struct bitmask* mask numa_bitmask_alloc(numa_max_node() 1); numa_bitmask_clearall(mask); numa_bitmask_setbit(mask, numa_node_id); numa_set_membind(mask); numa_bitmask_free(mask); }注意numa_set_membind()需libnuma库支持且进程需有CAP_SYS_NICE权限或以 root 运行若目标系统无 numactl可改用mbind()系统调用但复杂度显著上升。4. 解析 PCI 设备拓扑定位 GPU 与 CPU 的物理距离4.1 启用 PCI 探测的必要编译选项hwloc 默认关闭 PCI 扫描因需访问/sys/bus/pci/devices/部分容器环境无权限。启用方法已在 2.1 节给出--enable-pci但还需确保运行时有权限# 检查 PCI 设备是否可见 ls /sys/bus/pci/devices/ | head -5 # 若为空需在容器中添加 --privileged 或 --cap-addSYS_ADMIN4.2 获取 GPU 所在 NUMA 节点的三步法NVIDIA GPU 的PCIe BDFBus:Device.Function可通过nvidia-smi -L查得但要获知其物理 NUMA 节点必须走 hwloc 的 PCI 路径// find_gpu_numa.c #include hwloc.h #include stdio.h #include string.h // 根据 PCI 地址字符串如 0000:01:00.0查找对应对象 hwloc_obj_t find_pci_device_by_busid(hwloc_topology_t topo, const char* busid) { hwloc_obj_t obj; hwloc_obj_t next NULL; while ((obj hwloc_get_next_obj_by_type(topo, HWLOC_OBJ_PCI_DEVICE, next)) ! NULL) { // hwloc PCI 对象的 busid 格式为 0000:01:00.0 if (obj-attr obj-attr-pcidev.busid strcmp(obj-attr-pcidev.busid, busid) 0) { return obj; } next obj; } return NULL; } int main(int argc, char** argv) { if (argc ! 2) { fprintf(stderr, Usage: %s PCI_BUS_ID\n, argv[0]); fprintf(stderr, Example: %s 0000:01:00.0\n, argv[0]); return 1; } hwloc_topology_t topo; hwloc_topology_init(topo); hwloc_topology_load(topo); hwloc_obj_t gpu find_pci_device_by_busid(topo, argv[1]); if (!gpu) { fprintf(stderr, GPU not found: %s\n, argv[1]); return 1; } // 向上遍历父对象直到找到 NUMA 节点 hwloc_obj_t parent gpu; while (parent parent-type ! HWLOC_OBJ_NODE) { parent parent-parent; } if (parent) { printf(GPU %s is under NUMA node %d\n, argv[1], parent-logical_index); } else { printf(GPU %s has no NUMA node parent\n, argv[1]); } hwloc_topology_destroy(topo); return 0; }编译并运行需先用lspci -nn | grep NVIDIA获取 BDFgcc -I/usr/local/hwloc-2.9.0/include -L/usr/local/hwloc-2.9.0/lib -lhwloc find_gpu_numa.c -o find_gpu_numa ./find_gpu_numa 0000:01:00.0 # 输出GPU 0000:01:00.0 is under NUMA node 04.3 生成 CPU-GPU 亲和性建议表实战表格以下脚本输出所有 GPU 及其推荐绑定的 CPU 列表基于共享 L3 Cache 或同一 NUMA 节点GPU BDFNUMA NodeRecommended CPUs (OS Index)Shared L3 Cache?0000:01:00.000-15, 32-47Yes0000:02:00.0116-31, 48-63Yes生成逻辑在 C 中实现如下// generate_affinity_table.c 节选关键循环 hwloc_obj_t gpu; hwloc_obj_t next_gpu NULL; while ((gpu hwloc_get_next_obj_by_type(topo, HWLOC_OBJ_PCI_DEVICE, next_gpu)) ! NULL) { if (!gpu-attr || !gpu-attr-pcidev.class_id || (gpu-attr-pcidev.class_id 8) ! 0x03) // 0x03xx display controller continue; // 找 NUMA 父节点 hwloc_obj_t node NULL; hwloc_obj_t p gpu; while (p p-type ! HWLOC_OBJ_NODE) p p-parent; if (p) node p; printf(%s | %d | , gpu-attr-pcidev.busid, node ? node-logical_index : -1); // 打印该 NUMA 节点下所有 PU 的 os_index hwloc_obj_t pu; hwloc_obj_t next_pu NULL; int first 1; while ((pu hwloc_get_next_obj_by_type(topo, HWLOC_OBJ_PU, next_pu)) ! NULL) { if (node hwloc_bitmap_isset(pu-nodeset, node-logical_index)) { if (!first) printf(, ); printf(%u, pu-os_index); first 0; } next_pu pu; } printf( |\n); }5. 调试 hwloc 常见故障从 segfault 到静默失败5.1hwloc_topology_load()返回负值的 3 类根源该函数失败不抛异常只返回0需主动检查错误码常见原因诊断命令-1权限不足无法读取/sys/firmware/acpi/tables/sudo strace -e traceopenat,read ./your_program 21 | grep acpi-2内核不支持如旧版 CentOS 7 的 kernel-3.10 无完整 ACPI 表dmesg | grep -i acpi检查ACPI: EC: GPE query failed类错误-3hwloc 构建时未启用对应探测器如--disable-pci但代码调用 PCI 函数ldd your_binary | grep hwloc确认链接的是你编译的版本而非系统旧版5.2 对象指针为 NULL 的 2 个隐蔽场景// 场景 1查询不存在的 NUMA 节点 hwloc_obj_t node hwloc_get_obj_by_type(topo, HWLOC_OBJ_NODE, 999); // 节点 999 不存在 if (!node) { /* 不要直接解引用*/ } // 场景 2对象无 cpuset如某些虚拟化环境中的 PCI 设备 if (gpu-cpuset hwloc_bitmap_weight(gpu-cpuset) 0) { // 安全遍历 } else { // 回退到父节点 cpuset if (gpu-parent gpu-parent-cpuset) { // 使用 parent-cpuset } }5.3 用hwloc-info命令行工具快速验证拓扑完整性不写 C 也能调试hwloc-info是随 hwloc 安装的诊断工具比lscpu更细粒度# 输出完整拓扑树含缓存层级 hwloc-info -p # 检查特定对象属性 hwloc-info --object-type Core --only os_index,logical_index,nodeset # 导出为 XML 供离线分析可被 hwloc-view 图形化 hwloc-info --export-xml topology.xml若hwloc-info报No topology loaded说明环境变量HWLOC_XMLFILE指向了损坏的 XML 文件或/proc不可读。此时可强制重新探测HWLOC_COMPONENTS-linuxcpuid,-x86cpuid hwloc-info -p # 禁用易出错的 CPUID 探测器改用更稳定的 /proc/cpuinfo5.4 在容器中运行 hwloc 的 4 项必需挂载Docker/Kubernetes 中 hwloc 常返回单 socket 单 core因缺失关键 proc/sysfs# Dockerfile 片段 FROM ubuntu:22.04 COPY --frombuilder /usr/local/hwloc-2.9.0 /usr/local/hwloc-2.9.0 RUN ln -sf /usr/local/hwloc-2.9.0/bin/hwloc-info /usr/local/bin/ # 运行时必须挂载 # docker run -v /proc:/proc:ro -v /sys:/sys:ro -v /dev:/dev:ro --cap-addSYS_ADMIN your-image关键点/proc和/sys必须ro只读避免容器内修改宿主机状态--cap-addSYS_ADMIN是因 hwloc 需CAP_SYS_ADMIN访问/sys/firmware/acpi/tables/若仍失败可降级使用--enable-synthetic构建一个模拟拓扑仅用于测试勿用于生产。6. 用 hwloc 导出拓扑快照做 CI/CD 环境一致性校验6.1 生成可 diff 的文本拓扑摘要每次部署前将当前机器拓扑导出为标准化文本存入 Git# 生成摘要只保留 socket/core/PU 数量、NUMA 节点数、PCI 设备列表 { echo TOPOLOGY SNAPSHOT $(date -Iseconds) ; echo Sockets: $(hwloc-info --object-type Socket --no-children --only os_index 2/dev/null | wc -l); echo Cores: $(hwloc-info --object-type Core --no-children --only os_index 2/dev/null | wc -l); echo NUMA Nodes: $(hwloc-info --object-type Node --no-children --only os_index 2/dev/null | wc -l); echo GPUs: $(lspci -nn | grep -c 0300); echo PCIe Root Ports: $(lspci -t | grep -c Root Port); } topology-summary.txtCI 流水线中加入校验步骤# .gitlab-ci.yml 片段 check-topology: script: - diff -q topology-summary.txt expected-topology.txt || (echo Topology mismatch!; exit 1)6.2 在 C 程序启动时自动校验拓扑兼容性将上述逻辑嵌入主程序避免在错误拓扑上运行// topology_guard.c #include hwloc.h #include stdio.h #include stdlib.h #include string.h int check_topology_compatibility() { hwloc_topology_t topo; hwloc_topology_init(topo); if (hwloc_topology_load(topo) 0) { fprintf(stderr, Failed to load topology\n); return -1; } int sockets hwloc_get_nbobjs_by_type(topo, HWLOC_OBJ_SOCKET); int cores hwloc_get_nbobjs_by_type(topo, HWLOC_OBJ_CORE); int nodes hwloc_get_nbobjs_by_type(topo, HWLOC_OBJ_NODE); // 要求至少 2 socket、64 core、2 NUMA node if (sockets 2 || cores 64 || nodes 2) { fprintf(stderr, Topology too small: %d sockets, %d cores, %d NUMA nodes\n, sockets, cores, nodes); hwloc_topology_destroy(topo); return -1; } hwloc_topology_destroy(topo); return 0; } // 在 main() 开头调用 int main() { if (check_topology_compatibility() 0) { return 1; } // ... 正常逻辑 }6.3 用 hwloc 的 XML 导出做跨平台拓扑复现当需在无物理硬件的开发机上模拟服务器拓扑时可导出 XML 并加载# 在目标服务器上 hwloc-info --export-xml server-topology.xml # 在开发机上无需 root无需真实硬件 HWLOC_XMLFILEserver-topology.xml ./your_program此时hwloc_topology_load()读取 XML 而非探测硬件所有hwloc_get_*查询返回与服务器完全一致的结果。此技巧广泛用于 HPC 调度器单元测试、Kubernetes Device Plugin 模拟等场景。注意XML 文件包含绝对路径如/sys/devices/system/node/node0但 hwloc 加载时会忽略路径字段只用其中的层级结构和属性因此可安全跨机器复用。本文还有配套的精品资源点击获取
