Hardware Locality (hwloc)
1.7.2
|
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. linux
or solaris
) and the pci
miscellaneous 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_libxml
and xml_nolibxml
) but these will not be discussed here (see libxml2 and minimalistic XML backends).
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 pci
.
Usually the native operating system component (when it exists, e.g. linux
or 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 x86
and pci
, 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 x86
component).
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.
Once topology configuration functions such as hwloc_topology_set_custom()
have been taken care of, the priority order of the remaining components may be changed through the HWLOC_COMPONENTS
environment variable (component names must be separated by commas).
Specifying 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 some components from being loaded by prefixing their name with -
in the list. For instance x86,-pci
will load the x86
component, then let hwloc load all the usual components except pci
.
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 (xml
and synthetic
) accept an argument (e.g. xml=file.xml
). These arguments behave exactly as if the corresponding string had been passed to hwloc_topology_set_xml()
or hwloc_topology_set_synthetic()
.
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.
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.
Also note that plugins should carefully be enabled and used when embedding hwloc in another project, see Embedding hwloc in Other Software for details.
The types and functions cited below are declared in the hwloc/plugins.h header. Components are supposed to only use hwloc public headers (hwloc.h and anything under the include/hwloc
subdirectory) and nothing from the include/private
subdirectory in the source tree.
Each discovery component is defined by a hwloc_disc_component
structure which contains an instantiate()
callback. This function is invoked when this component is actually used by a topology. It fills a new hwloc_backend
structure that usually contains discover()
and/or notify_new_object()
callbacks taking care of the actual topology discovery.
Registering components to the hwloc core relies on a hwloc_component
structure. Its data
field points to the previously defined hwloc_disc_component
structure while its type
should be HWLOC_COMPONENT_TYPE_DISC. This structure should be named hwloc_<name>_component
.
The configure script should be modified to add <name>
to its hwloc_components
shell variable so that the component is actually available.
hwloc_component
structure is independent of the name of the discovery component mentioned in the previous section.When the component is statically built inside the hwloc library, the symbol hwloc_<name>_component
is added by configure to the src/static-components.h
. The core then registers all components listed in this file.
If the new component may be built as a plugin, the configure script should also define the shell variable hwloc_<name>_component_maybeplugin=1
. When the configure script actually enables the component as a plugin, it will set the variable hwloc_<name>_component
to plugin
. The build system may then use this variable to change the way the component is built. It should create a hwloc_<name>.so
shared object. All these files are loaded in alphabetic order, and the components they contain are registered to the hwloc core.
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).
–host=powerpc64-bgq-linux
is passed to configure (see How do I build hwloc for BlueGene/Q?).