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 package each, with one cache above two single-threaded cores:
$ lstopo -i "node:2 pack:1 cache:1 core:2 pu:1" -
Machine (2048MB)
NUMANode L#0 (P#0 1024MB) + Package 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) + Package 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.
- Note
- Synthetic topologies offer a very basic way to export a topology and reimport it on another machine. It is a lot less precise than XML but may still be enough when only the hierarchy of resources matters.
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, numanode, package, core, cache, pu, 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 and Misc 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.) unless they are specified. Memory and cache sizes are also automatically chosen if needed.
Each item may be followed parentheses containing a list of space-separated attributes. For instance:
-
L2iCache:2(size=32kB) specifies 2 children of 32kB level-2 instruction caches. The size may be specified in bytes (without any unit suffix) or as TB, GB, MB or kB.
-
NUMANode:3(memory=16MB) specifies 3 NUMA nodes with 16MB each. The size may be specified in bytes (without any unit suffix) or as TB, GB, MB or kB.
-
PU:2(indexes=0,2,1,3) specifies 2 PU children and the full list of OS indexes among the entire set of 4 PU objects.
-
PU:2(indexes=numa:core) specifies 2 PU children whose OS indexes are interleaved by NUMA node first and then by package.
-
Attributes in parentheses at the very beginning of the description apply to the root object.
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
The function hwloc_topology_export_synthetic() may export a topology as a synthetic string. It offers a convenient way to quickly describe the contents of a machine. The lstopo tool may also perform such an export by forcing the output format.
$ lstopo --of synthetic --no-io
Package: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 some attributes such as the processor model will be missing.
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 asymmetric. Passing --no-io to lstopo is therefore often useful to make synthetic export work (as well as not passing any I/O topology flag before exporting with hwloc_topology_export_synthetic()).
