Open MPI logo

Portable Hardware Locality (hwloc) Documentation: v1.9

  |   Home   |   Support   |   FAQ   |  
Synthetic topologies

hwloc may load fake or remote topologies so as to consult them without having the underlying hardware available. Aside from loading XML topologies, hwloc also enables the building of synthetic topologies that are described by a single string listing the arity of each levels.

For instance, lstopo may create a topology made of 2 NUMA nodes, containing a single socket each, with one cache above two single-threaded cores:

$ lstopo -i "node:2 sock:1 cache:1 core:2 pu:1" -
Machine (2048MB)
  NUMANode L#0 (P#0 1024MB) + Socket L#0 + L2 L#0 (4096KB)
    Core L#0 + PU L#0 (P#0)
    Core L#1 + PU L#1 (P#1)
  NUMANode L#1 (P#1 1024MB) + Socket L#1 + L2 L#1 (4096KB)
    Core L#2 + PU L#2 (P#2)
    Core L#3 + PU L#3 (P#3)

Replacing - with file.xml in this command line will export this topology to XML as usual.

Synthetic description string

Each item in the description string gives the type of the level and the number of such children under each object of the previous level. That is why the above topology contains 4 cores (2 cores times 2 nodes).

These type names must be written as machine, node, socket, core, cache, pu, misc, group. They do not need to be written case-sensitively, nor entirely (as long as there is no ambiguity, 2 characters such as ma select a Machine level). Type-specific attributes may also be given such as L2iCache (hwloc_obj_type_sscanf() is used for parsing the type names). Note that I/O objects are not available.

The root object does not appear in the string. A Machine object is used by default, and a System object replaces it if a Machine level is specified in the string.

Cache level depths are automatically chosen by hwloc (only a L2 first, then a L1 under it, then L3 above, then L4 etc.). Memory and cache sizes are also automatically chosen. The only way to modifying them is to export to XML and manually modify the file.

Loading a synthetic topology

Aside from lstopo, the hwloc programming interface offers the same ability by passing the synthetic description string to hwloc_topology_set_synthetic() before hwloc_topology_load().

Synthetic topologies are created by the synthetic component. This component may be enabled by force by setting the HWLOC_COMPONENTS environment variable to something such as synthetic="node:2 core:3 pu:4".

Loading a synthetic topology disables binding support since the topology usually does not match the underlying hardware. Binding may be reenabled as usual by setting HWLOC_THISSYSTEM=1 in the environment or by setting the HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM topology flag.

Exporting a topology as a synthetic string

lstopo may export a topology as a synthetic string by forcing its output format. It offers a convenient way to quickly describe the contents of a machine.

$ lstopo --of synthetic --no-io
Socket:1 Cache:1 Cache:2 Cache:1 Cache:1 Core:1 PU:2 

The exported string may be passed back to hwloc for recreating another similar topology. The entire tree will be similar, but cache types and memory sizes may be different from the originals.

Such an export is only possible if the topology is totally symmetric, which means the symmetric_subtree field of the root object is set. This usually implies that I/O objects are disabled since attaching I/O busses often cause the topology to become assymetric. Passing –no-io to lstopo is therefore often useful to make synthetic export work (as well as not passing any I/O topology flag when using hwloc_topology_set_synthetic() manually).