{"id":13785595,"url":"https://github.com/open-mpi/hwloc","last_synced_at":"2026-02-09T12:15:06.151Z","repository":{"id":10822596,"uuid":"13098944","full_name":"open-mpi/hwloc","owner":"open-mpi","description":"Hardware locality (hwloc)","archived":false,"fork":false,"pushed_at":"2024-03-26T10:07:31.000Z","size":41342,"stargazers_count":518,"open_issues_count":131,"forks_count":162,"subscribers_count":39,"default_branch":"master","last_synced_at":"2024-03-27T11:22:13.510Z","etag":null,"topics":["c","hardware","hpc","locality","topology"],"latest_commit_sha":null,"homepage":"https://www.open-mpi.org/projects/hwloc","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/open-mpi.png","metadata":{"files":{"readme":"README","changelog":null,"contributing":".github/contributing.md","funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null}},"created_at":"2013-09-25T16:25:32.000Z","updated_at":"2024-07-04T09:00:39.419Z","dependencies_parsed_at":"2023-12-20T16:48:12.356Z","dependency_job_id":"20dfec0f-0671-48fe-8a4d-5e7485589aee","html_url":"https://github.com/open-mpi/hwloc","commit_stats":null,"previous_names":[],"tags_count":148,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-mpi%2Fhwloc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-mpi%2Fhwloc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-mpi%2Fhwloc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-mpi%2Fhwloc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/open-mpi","download_url":"https://codeload.github.com/open-mpi/hwloc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247898519,"owners_count":21014722,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","hardware","hpc","locality","topology"],"created_at":"2024-08-03T19:01:02.264Z","updated_at":"2026-02-09T12:15:06.126Z","avatar_url":"https://github.com/open-mpi.png","language":"C","funding_links":[],"categories":["NUMA library bindings and interfaces"],"sub_categories":[],"readme":"This is a truncated and poorly-formatted version of the documentation main page.\nSee https://www.open-mpi.org/projects/hwloc/doc/ for more.\n\n\nhwloc Overview\n\nThe Hardware Locality (hwloc) software project aims at easing the process of\ndiscovering hardware resources in parallel architectures. It offers\ncommand-line tools and a C API for consulting these resources, their locality,\nattributes, and interconnection. hwloc primarily aims at helping\nhigh-performance computing (HPC) applications, but is also applicable to any\nproject seeking to exploit code and/or data locality on modern computing\nplatforms.\n\nhwloc provides command line tools and a C API to obtain the hierarchical map of\nkey computing elements within a node, such as: NUMA memory nodes, shared\ncaches, processor packages, dies and cores, processing units (logical\nprocessors or \"threads\") and even I/O devices. hwloc also gathers various\nattributes such as cache and memory information, and is portable across a\nvariety of different operating systems and platforms.\n\nhwloc primarily aims at helping high-performance computing (HPC) applications,\nbut is also applicable to any project seeking to exploit code and/or data\nlocality on modern computing platforms.\n\nhwloc supports the following operating systems:\n\n  * Linux (with knowledge of cgroups and cpusets, memory targets/initiators,\n etc.) on all supported hardware, including Intel Xeon Phi, ScaleMP vSMP,\n and NumaScale NumaConnect.\n  * Solaris (with support for processor sets and logical domains)\n  * AIX\n  * Darwin / OS X\n  * FreeBSD and its variants (such as kFreeBSD/GNU)\n  * NetBSD\n  * Microsoft Windows\n\nSince it uses standard Operating System information, hwloc's support is mostly\nindependant from the processor type (x86, powerpc, ...) and just relies on the\nOperating System support. The main exception is BSD operating systems (NetBSD,\nFreeBSD, etc.) because they do not provide support topology information, hence\nhwloc uses an x86-only CPUID-based backend (which can be used for other OSes\ntoo, see the Components and plugins section).\n\nTo check whether hwloc works on a particular machine, just try to build it and\nrun lstopo or lstopo-no-graphics. If some things do not look right (e.g. bogus\nor missing cache information), see Questions and Bugs.\n\nhwloc only reports the number of processors on unsupported operating systems;\nno topology information is available.\n\nFor development and debugging purposes, hwloc also offers the ability to work\non \"fake\" topologies:\n\n  * Symmetrical tree of resources generated from a list of level arities, see\n Synthetic topologies.\n  * Remote machine simulation through the gathering of topology as XML files,\n see Importing and exporting topologies from/to XML files.\n\nhwloc can display the topology in a human-readable format, either in graphical\nmode (X11), or by exporting in one of several different formats, including:\nplain text, LaTeX tikzpicture, PDF, PNG, and FIG (see Command-line Examples\nbelow). Note that some of the export formats require additional support\nlibraries.\n\nhwloc offers a programming interface for manipulating topologies and objects.\nIt also brings a powerful CPU bitmap API that is used to describe topology\nobjects location on physical/logical processors. See the Programming Interface\nbelow. It may also be used to binding applications onto certain cores or memory\nnodes. Several utility programs are also provided to ease command-line\nmanipulation of topology objects, binding of processes, and so on.\n\nBindings for several other languages are available from the project website.\n\nCommand-line Examples\n\nOn a 4-package 2-core machine with hyper-threading, the lstopo tool may show\nthe following graphical output:\n\n[dudley]\n\nHere's the equivalent output in textual form:\n\nMachine\n  NUMANode L#0 (P#0)\n  Package L#0 + L3 L#0 (4096KB)\n L2 L#0 (1024KB) + L1 L#0 (16KB) + Core L#0\n   PU L#0 (P#0)\n   PU L#1 (P#8)\n L2 L#1 (1024KB) + L1 L#1 (16KB) + Core L#1\n   PU L#2 (P#4)\n   PU L#3 (P#12)\n  Package L#1 + L3 L#1 (4096KB)\n L2 L#2 (1024KB) + L1 L#2 (16KB) + Core L#2\n   PU L#4 (P#1)\n   PU L#5 (P#9)\n L2 L#3 (1024KB) + L1 L#3 (16KB) + Core L#3\n   PU L#6 (P#5)\n   PU L#7 (P#13)\n  Package L#2 + L3 L#2 (4096KB)\n L2 L#4 (1024KB) + L1 L#4 (16KB) + Core L#4\n   PU L#8 (P#2)\n   PU L#9 (P#10)\n L2 L#5 (1024KB) + L1 L#5 (16KB) + Core L#5\n   PU L#10 (P#6)\n   PU L#11 (P#14)\n  Package L#3 + L3 L#3 (4096KB)\n L2 L#6 (1024KB) + L1 L#6 (16KB) + Core L#6\n   PU L#12 (P#3)\n   PU L#13 (P#11)\n L2 L#7 (1024KB) + L1 L#7 (16KB) + Core L#7\n   PU L#14 (P#7)\n   PU L#15 (P#15)\n\nNote that there is also an equivalent output in XML that is meant for exporting\n/importing topologies but it is hardly readable to human-beings (see Importing\nand exporting topologies from/to XML files for details).\n\nOn a 4-package 2-core Opteron NUMA machine (with two core cores disallowed by\nthe administrator), the lstopo tool may show the following graphical output\n(with --disallowed for displaying disallowed objects):\n\n[hagrid]\n\nHere's the equivalent output in textual form:\n\nMachine (32GB total)\n  Package L#0\n NUMANode L#0 (P#0 8190MB)\n L2 L#0 (1024KB) + L1 L#0 (64KB) + Core L#0 + PU L#0 (P#0)\n L2 L#1 (1024KB) + L1 L#1 (64KB) + Core L#1 + PU L#1 (P#1)\n  Package L#1\n NUMANode L#1 (P#1 8192MB)\n L2 L#2 (1024KB) + L1 L#2 (64KB) + Core L#2 + PU L#2 (P#2)\n L2 L#3 (1024KB) + L1 L#3 (64KB) + Core L#3 + PU L#3 (P#3)\n  Package L#2\n NUMANode L#2 (P#2 8192MB)\n L2 L#4 (1024KB) + L1 L#4 (64KB) + Core L#4 + PU L#4 (P#4)\n L2 L#5 (1024KB) + L1 L#5 (64KB) + Core L#5 + PU L#5 (P#5)\n  Package L#3\n NUMANode L#3 (P#3 8192MB)\n L2 L#6 (1024KB) + L1 L#6 (64KB) + Core L#6 + PU L#6 (P#6)\n L2 L#7 (1024KB) + L1 L#7 (64KB) + Core L#7 + PU L#7 (P#7)\n\nOn a 2-package quad-core Xeon (pre-Nehalem, with 2 dual-core dies into each\npackage):\n\n[emmett]\n\nHere's the same output in textual form:\n\nMachine (total 16GB)\n  NUMANode L#0 (P#0 16GB)\n  Package L#0\n L2 L#0 (4096KB)\n   L1 L#0 (32KB) + Core L#0 + PU L#0 (P#0)\n   L1 L#1 (32KB) + Core L#1 + PU L#1 (P#4)\n L2 L#1 (4096KB)\n   L1 L#2 (32KB) + Core L#2 + PU L#2 (P#2)\n   L1 L#3 (32KB) + Core L#3 + PU L#3 (P#6)\n  Package L#1\n L2 L#2 (4096KB)\n   L1 L#4 (32KB) + Core L#4 + PU L#4 (P#1)\n   L1 L#5 (32KB) + Core L#5 + PU L#5 (P#5)\n L2 L#3 (4096KB)\n   L1 L#6 (32KB) + Core L#6 + PU L#6 (P#3)\n   L1 L#7 (32KB) + Core L#7 + PU L#7 (P#7)\n\nProgramming Interface\n\nThe basic interface is available in hwloc.h. Some higher-level functions are\navailable in hwloc/helper.h to reduce the need to manually manipulate objects\nand follow links between them. Documentation for all these is provided later in\nthis document. Developers may also want to look at hwloc/inlines.h which\ncontains the actual inline code of some hwloc.h routines, and at this document,\nwhich provides good higher-level topology traversal examples.\n\nTo precisely define the vocabulary used by hwloc, a Terms and Definitions\nsection is available and should probably be read first.\n\nEach hwloc object contains a cpuset describing the list of processing units\nthat it contains. These bitmaps may be used for CPU binding and Memory binding.\nhwloc offers an extensive bitmap manipulation interface in hwloc/bitmap.h.\n\nMoreover, hwloc also comes with additional helpers for interoperability with\nseveral commonly used environments. See the Interoperability With Other\nSoftware section for details.\n\nThe complete API documentation is available in a full set of HTML pages, man\npages, and self-contained PDF files (formatted for both both US letter and A4\nformats) in the source tarball in doc/doxygen-doc/.\n\nNOTE: If you are building the documentation from a Git clone, you will need to\nhave Doxygen and pdflatex installed -- the documentation will be built during\nthe normal \"make\" process. The documentation is installed during \"make install\"\nto $prefix/share/doc/hwloc/ and your systems default man page tree (under\n$prefix, of course).\n\nPortability\n\nOperating System have varying support for CPU and memory binding, e.g. while\nsome Operating Systems provide interfaces for all kinds of CPU and memory\nbindings, some others provide only interfaces for a limited number of kinds of\nCPU and memory binding, and some do not provide any binding interface at all.\nHwloc's binding functions would then simply return the ENOSYS error (Function\nnot implemented), meaning that the underlying Operating System does not provide\nany interface for them. CPU binding and Memory binding provide more information\non which hwloc binding functions should be preferred because interfaces for\nthem are usually available on the supported Operating Systems.\n\nSimilarly, the ability of reporting topology information varies from one\nplatform to another. As shown in Command-line Examples, hwloc can obtain\ninformation on a wide variety of hardware topologies. However, some platforms\nand/or operating system versions will only report a subset of this information.\nFor example, on an PPC64-based system with 8 cores (each with 2 hardware\nthreads) running a default 2.6.18-based kernel from RHEL 5.4, hwloc is only\nable to glean information about NUMA nodes and processor units (PUs). No\ninformation about caches, packages, or cores is available.\n\nHere's the graphical output from lstopo on this platform when Simultaneous\nMulti-Threading (SMT) is enabled:\n\n[ppc64-with]\n\nAnd here's the graphical output from lstopo on this platform when SMT is\ndisabled:\n\n[ppc64-with]\n\nNotice that hwloc only sees half the PUs when SMT is disabled. PU L#6, for\nexample, seems to change location from NUMA node #0 to #1. In reality, no PUs\n\"moved\" -- they were simply re-numbered when hwloc only saw half as many (see\nalso Logical index in Indexes and Sets). Hence, PU L#6 in the SMT-disabled\npicture probably corresponds to PU L#12 in the SMT-enabled picture.\n\nThis same \"PUs have disappeared\" effect can be seen on other platforms -- even\nplatforms / OSs that provide much more information than the above PPC64 system.\nThis is an unfortunate side-effect of how operating systems report information\nto hwloc.\n\nNote that upgrading the Linux kernel on the same PPC64 system mentioned above\nto 2.6.34, hwloc is able to discover all the topology information. The\nfollowing picture shows the entire topology layout when SMT is enabled:\n\n[ppc64-full]\n\nDevelopers using the hwloc API or XML output for portable applications should\ntherefore be extremely careful to not make any assumptions about the structure\nof data that is returned. For example, per the above reported PPC topology, it\nis not safe to assume that PUs will always be descendants of cores.\n\nAdditionally, future hardware may insert new topology elements that are not\navailable in this version of hwloc. Long-lived applications that are meant to\nspan multiple different hardware platforms should also be careful about making\nstructure assumptions. For example, a new element may someday exist between a\ncore and a PU.\n\nAPI Example\n\nThe following small C example (available in the source tree as ``doc/examples/\nhwloc-hello.c'') prints the topology of the machine and performs some thread\nand memory binding. More examples are available in the doc/examples/ directory\nof the source tree.\n\n/*\n* SPDX-License-Identifier: BSD-3-Clause\n* Copyright © 2009-2026 Inria.  All rights reserved.\n* Copyright (c) 2009-2011 Universit?eacute; Bordeaux\n* Copyright (c) 2009-2010 Cisco Systems, Inc. All rights reserved.\n* See COPYING in top-level directory.\n*\n* Example hwloc API program.\n*\n* See other examples under doc/examples/ in the source tree\n* for more details.\n*\n* hwloc-hello.c\n*/\n#include \"hwloc.h\"\n#include \u003cerrno.h\u003e\n#include \u003cstdio.h\u003e\n#include \u003cstring.h\u003e\nstatic void print_children(hwloc_topology_t topology, hwloc_obj_t obj,\nint depth)\n{\nchar type[32], attr[1024];\nunsigned i;\nhwloc_obj_type_snprintf(type, sizeof(type), obj, 0);\nprintf(\"%*s%s\", 2*depth, \"\", type);\nif (obj-\u003eos_index != (unsigned) -1)\nprintf(\"#%u\", obj-\u003eos_index);\nhwloc_obj_attr_snprintf(attr, sizeof(attr), obj, \" \", 0);\nif (*attr)\nprintf(\"(%s)\", attr);\nprintf(\"\\n\");\nfor (i = 0; i \u003c obj-\u003earity; i++) {\nprint_children(topology, obj-\u003echildren[i], depth + 1);\n}\n}\nint main(void)\n{\nint depth;\nunsigned i, n;\nunsigned long size;\nint levels;\nchar string[128];\nint topodepth;\nvoid *m;\nhwloc_topology_t topology;\nhwloc_cpuset_t cpuset;\nhwloc_obj_t obj;\n/* Allocate and initialize topology object. */\nhwloc_topology_init(\u0026topology);\n/* ... Optionally, put detection configuration here to ignore\nsome objects types, define a synthetic topology, etc....\nThe default is to detect all the objects of the machine that\nthe caller is allowed to access. See Configure Topology\nDetection. */\n/* Perform the topology detection. */\nhwloc_topology_load(topology);\n/* Optionally, get some additional topology information\nin case we need the topology depth later. */\ntopodepth = hwloc_topology_get_depth(topology);\n/*****************************************************************\n* First example:\n* Walk the topology with an array style, from level 0 (always\n* the system level) to the lowest level (always the proc level).\n*****************************************************************/\nfor (depth = 0; depth \u003c topodepth; depth++) {\nprintf(\"*** Objects at level %d\\n\", depth);\nfor (i = 0; i \u003c hwloc_get_nbobjs_by_depth(topology, depth);\ni++) {\nhwloc_obj_type_snprintf(string, sizeof(string),\nhwloc_get_obj_by_depth(topology, depth, i), 0);\nprintf(\"Index %u: %s\\n\", i, string);\n}\n}\n/*****************************************************************\n* Second example:\n* Walk the topology with a tree style.\n*****************************************************************/\nprintf(\"*** Printing overall tree\\n\");\nprint_children(topology, hwloc_get_root_obj(topology), 0);\n/*****************************************************************\n* Third example:\n* Print the number of packages.\n*****************************************************************/\ndepth = hwloc_get_type_depth(topology, HWLOC_OBJ_PACKAGE);\nif (depth == HWLOC_TYPE_DEPTH_UNKNOWN) {\nprintf(\"*** The number of packages is unknown\\n\");\n} else {\nprintf(\"*** %u package(s)\\n\",\nhwloc_get_nbobjs_by_depth(topology, depth));\n}\n/*****************************************************************\n* Fourth example:\n* Compute the amount of cache that the first logical processor\n* has above it.\n*****************************************************************/\nlevels = 0;\nsize = 0;\nfor (obj = hwloc_get_obj_by_type(topology, HWLOC_OBJ_PU, 0);\nobj;\nobj = obj-\u003eparent)\nif (hwloc_obj_type_is_cache(obj-\u003etype)) {\nlevels++;\nsize += obj-\u003eattr-\u003ecache.size;\n}\nprintf(\"*** Logical processor 0 has %d caches totaling %luKB\\n\",\nlevels, size / 1024);\n/*****************************************************************\n* Fifth example:\n* Bind to only one thread of the last core of the machine.\n*\n* First find out where cores are, or else smaller sets of CPUs if\n* the OS doesn't have the notion of a \"core\".\n*****************************************************************/\ndepth = hwloc_get_type_or_below_depth(topology, HWLOC_OBJ_CORE);\n/* Get last core. */\nobj = hwloc_get_obj_by_depth(topology, depth,\nhwloc_get_nbobjs_by_depth(topology, depth) - 1);\nif (obj) {\n/* Get a copy of its cpuset that we may modify. */\ncpuset = hwloc_bitmap_dup(obj-\u003ecpuset);\n/* Get only one logical processor (in case the core is\nSMT/hyper-threaded). */\nhwloc_bitmap_singlify(cpuset);\n/* And try to bind ourself there. */\nif (hwloc_set_cpubind(topology, cpuset, 0)) {\nchar *str;\nint error = errno;\nhwloc_bitmap_asprintf(\u0026str, obj-\u003ecpuset);\nprintf(\"Couldn't bind to cpuset %s: %s\\n\", str, strerror(error));\nfree(str);\n}\n/* Free our cpuset copy */\nhwloc_bitmap_free(cpuset);\n}\n/*****************************************************************\n* Sixth example:\n* Allocate some memory on the last NUMA node, bind some existing\n* memory to the last NUMA node.\n*****************************************************************/\n/* Get last node. There's always at least one. */\nn = hwloc_get_nbobjs_by_type(topology, HWLOC_OBJ_NUMANODE);\nobj = hwloc_get_obj_by_type(topology, HWLOC_OBJ_NUMANODE, n - 1);\nsize = 1024*1024;\nm = hwloc_alloc_membind(topology, size, obj-\u003enodeset,\nHWLOC_MEMBIND_BIND, HWLOC_MEMBIND_BYNODESET);\nhwloc_free(topology, m, size);\nm = malloc(size);\nhwloc_set_area_membind(topology, m, size, obj-\u003enodeset,\nHWLOC_MEMBIND_BIND, HWLOC_MEMBIND_BYNODESET);\nfree(m);\n/* Destroy topology object. */\nhwloc_topology_destroy(topology);\nreturn 0;\n}\n\nhwloc provides a pkg-config executable to obtain relevant compiler and linker\nflags. See Compiling software on top of hwloc's C API for details on building\nprogram on top of hwloc's API using GNU Make or CMake.\n\nOn a machine 2 processor packages -- each package of which has two processing\ncores -- the output from running hwloc-hello could be something like the\nfollowing:\n\nshell$ ./hwloc-hello\n Objects at level 0\nIndex 0: Machine\n Objects at level 1\nIndex 0: Package#0\nIndex 1: Package#1\n Objects at level 2\nIndex 0: Core#0\nIndex 1: Core#1\nIndex 2: Core#3\nIndex 3: Core#2\n Objects at level 3\nIndex 0: PU#0\nIndex 1: PU#1\nIndex 2: PU#2\nIndex 3: PU#3\n Printing overall tree\nMachine\n  Package#0\n Core#0\n   PU#0\n Core#1\n   PU#1\n  Package#1\n Core#3\n   PU#2\n Core#2\n   PU#3\n 2 package(s)\n Logical processor 0 has 0 caches totaling 0KB\nshell$\n\nQuestions and Bugs\n\nBugs should be reported in the tracker (https://github.com/open-mpi/hwloc/\nissues). Opening a new issue automatically displays lots of hints about how to\ndebug and report issues.\n\nQuestions may be sent to the users or developers mailing lists (https://\nwww.open-mpi.org/community/lists/hwloc.php).\n\nThere is also a #hwloc IRC channel on Libera Chat (irc.libera.chat).\n\nHistory / Credits\n\nhwloc is the evolution and merger of the libtopology project and the Portable\nLinux Processor Affinity (PLPA) (https://www.open-mpi.org/projects/plpa/)\nproject. Because of functional and ideological overlap, these two code bases\nand ideas were merged and released under the name \"hwloc\" as an Open MPI\nsub-project.\n\nlibtopology was initially developed by the Inria Runtime Team-Project. PLPA was\ninitially developed by the Open MPI development team as a sub-project. Both are\nnow deprecated in favor of hwloc, which is distributed as an Open MPI\nsub-project.\n\n \n\n\nSee https://www.open-mpi.org/projects/hwloc/doc/ for more hwloc documentation,\nactual links to related pages, images, etc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-mpi%2Fhwloc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-mpi%2Fhwloc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-mpi%2Fhwloc/lists"}