hwloc is organized in components that are responsible for discovering objects. Depending on the topology configuration, some components will be used, some will be ignored. The usual default is to enable the native operating system component, (e.g.
solaris) and the
libpci additional component. If available, an architecture-specific component (such as
x86) may also improve the topology detection.
If a XML topology is loaded, the
xml discovery component will be used instead of all other components. It internally uses a specific class of components for the actual XML import/export routines (
xml_nolibxml) but these will not be discussed here (see libxml2 and minimalistic XML backends).
Components enabled by default
The hwloc core contains a list of components sorted by priority. Each one is enabled as long as it does not conflict with the previously enabled ones. This includes native operating system components, architecture-specific ones, and if available, I/O components such as
Usually the native operating system component (when it exists, e.g.
aix) is enabled first. Then hwloc looks for an architecture specific component (e.g.
x86). Finally these also exist a basic component (
no_os) that just tries to discover the number of PUs in the system.
Each component discovers as much topology information as possible. Most of them, including most native OS components, do nothing unless the topology is still empty. Some others, such as
libpci, can complete and annotate what other backends still earlier.
Default priorities ensure that clever components are invoked first. Native operating system components have higher priorities, and are therefore invoked first, because they likely offer very detailed topology information. If needed, it will be later extended by architecture-specific information (e.g. from the
If any configuration function such as hwloc_topology_set_xml() is used before loading the topology, the corresponding component is enabled first. Then, as usual, hwloc enables any other component (based on priorities) that does not conflict.
Certain components that manage a virtual topology, for instance XML topology import, synthetic topology description, or custom building, conflict with all other components. Therefore, one of them may only be loaded (e.g. with
hwloc_topology_set_xml()) if no other component is enabled.
The environment variable
HWLOC_COMPONENTS_VERBOSE may be set to get verbose messages about component registration (including their priority) and enabling.
Selecting which components to use
Aside from topology configuration function such as
hwloc_topology_set_custom(), the default priority order may be changed through the
HWLOC_COMPONENTS environment variable (component names must be separated by commas).
x86 in this variable will cause the
x86 component to take precedence over any other component, including the native operating system component. It is therefore loaded first, before hwloc tries to load all remaining non-conflicting components. In this case,
x86 would take care of discovering everything it supports, instead of only completing what the native OS information. This may be useful if the native component is buggy on some platforms.
It is possible to prevent all remaining components from being loaded by placing
stop in the environment variable. Only the components listed before this keyword will be enabled.
Certain component names (
synthetic) accept an argument (e.g.
xml=file.xml). These arguments behave exactly as if the corresponding string had been passed to
Building components as plugins
Components may optionally be built as plugins so that the hwloc core library does not directly depend on their dependencies (for instance the
libpci library). Plugin support may be enabled with the
–enable-plugins configure option. All components buildable as plugins will then be built as plugins. The configure option may be given a comma-separated list of component names to specify the exact list of components to build as plugins.
Plugins are built as independent dynamic libraries that are installed in
$libdir/hwloc. All plugins found in this directory are loaded during
topology_init(). A specific list of directories (colon-separated) to scan may be specified in the
HWLOC_PLUGINS_PATH environment variable.
Plugin filenames must start with
hwloc_. For instance the
libpci plugin is usually built as
Note that loading a plugin just means that the corresponding component is registered to the hwloc core. Components are then only enabled if the topology configuration requests it, as explained in the previous sections.
Adding new discovery components and plugins
Each new discovery component requires a new
hwloc_component structure to be exported to the hwloc core with name
hwloc_<name>_component. The configure script should then be modified to add
<name> to the
hwloc_components variable so that the component is actually available at runtime.
If the new component may be built as a plugin, the configure script should also define
hwloc_<name>_component_maybeplugin=1. If the configure scripts decides to enable the component as a plugin, the variable
hwloc_<name>_component will be set to
plugin. The build system may then use this variable to actually change the way the component is built.
The component structure contains a data field that points to an
hwloc_disc_component which defines an
instantiate callback. This function is invoked when this component is actually used by a topology. It creates a
backend structure that usually contains a
notify_new_object callback taking care of the actual topology discovery.
Existing components and plugins
All components distributed within hwloc are listed below. The list of actually available components may be listed at running with the
HWLOC_COMPONENTS_VERBOSE environment variable (see Environment Variables).
- aix, darwin, freebsd, hpux, linux, netbsd, osf, solaris, windows
- Each officially supported operating system has its own native component, which is statically built when supported, and which is used by default.
- The x86 architecture (either 32 or 64 bits) has its own component that may complete or replace the previously-found CPU information. It is statically built when supported.
- A basic component that just tries to detect the number of processing units in the system. It mostly serves on operating systems that are not natively supported. It is always statically built.
- PCI object discovery uses the external pciaccess library (aka libpciaccess), or optionally the pciutils library (libpci), see I/O Devices. It may be built as a plugin.
- Synthetic topology support (see Synthetic Topologies) is always built statically.
- Custom topology support (see Multi-node Topologies) is always built statically.
- XML topology import (see Importing and exporting topologies from/to XML files) is always built statically. It internally uses one of the XML backends (see libxml2 and minimalistic XML backends).
xml_nolibxml is a basic and hwloc-specific XML import/export. It is always statically built.
xml_libxml relies on the external libxml2 library for provinding a feature-complete XML import/export. It may be built as a plugin.
- A dummy plugin that does nothing but is used for debugging plugin support.