hwlocality_tinker - Man Page

enum hwloc_restrict_flags_e { HWLOC_RESTRICT_FLAG_REMOVE_CPULESS, HWLOC_RESTRICT_FLAG_BYNODESET = (1UL<<3), HWLOC_RESTRICT_FLAG_REMOVE_MEMLESS, HWLOC_RESTRICT_FLAG_ADAPT_MISC, HWLOC_RESTRICT_FLAG_ADAPT_IO }
enum hwloc_allow_flags_e { HWLOC_ALLOW_FLAG_ALL, HWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS, HWLOC_ALLOW_FLAG_CUSTOM }

int hwloc_topology_restrict (hwloc_topology_t restrict topology, hwloc_const_bitmap_t set, unsigned long flags)
int hwloc_topology_allow (hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, hwloc_const_nodeset_t nodeset, unsigned long flags)
hwloc_obj_t hwloc_topology_insert_misc_object (hwloc_topology_t topology, hwloc_obj_t parent, const char *name)
hwloc_obj_t hwloc_topology_alloc_group_object (hwloc_topology_t topology)
int hwloc_topology_free_group_object (hwloc_topology_t topology, hwloc_obj_t group)
hwloc_obj_t hwloc_topology_insert_group_object (hwloc_topology_t topology, hwloc_obj_t group)
int hwloc_obj_add_other_obj_sets (hwloc_obj_t dst, hwloc_obj_t src)
int hwloc_topology_refresh (hwloc_topology_t topology)

Flags to be given to hwloc_topology_allow()​.

Enumerator

HWLOC_ALLOW_FLAG_ALL

Mark all objects as allowed in the topology​. cpuset and nođeset given to hwloc_topology_allow() must be NULL​.

HWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS

Only allow objects that are available to the current process​. The topology must have HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM so that the set of available resources can actually be retrieved from the operating system​.

cpuset and nođeset given to hwloc_topology_allow() must be NULL​.

HWLOC_ALLOW_FLAG_CUSTOM

Allow a custom set of objects, given to hwloc_topology_allow() as cpuset and/or nodeset parameters​.

Flags to be given to hwloc_topology_restrict()​.

Enumerator

HWLOC_RESTRICT_FLAG_REMOVE_CPULESS

Remove all objects that became CPU-less​. By default, only objects that contain no PU and no memory are removed​. This flag may not be used with HWLOC_RESTRICT_FLAG_BYNODESET​.

HWLOC_RESTRICT_FLAG_BYNODESET

Restrict by nodeset instead of CPU set​. Only keep objects whose nodeset is included or partially included in the given set​. This flag may not be used with HWLOC_RESTRICT_FLAG_REMOVE_CPULESS​.

HWLOC_RESTRICT_FLAG_REMOVE_MEMLESS

Remove all objects that became Memory-less​. By default, only objects that contain no PU and no memory are removed​. This flag may only be used with HWLOC_RESTRICT_FLAG_BYNODESET​.

HWLOC_RESTRICT_FLAG_ADAPT_MISC

Move Misc objects to ancestors if their parents are removed during restriction​. If this flag is not set, Misc objects are removed when their parents are removed​.

HWLOC_RESTRICT_FLAG_ADAPT_IO

Move I/O objects to ancestors if their parents are removed during restriction​. If this flag is not set, I/O devices and bridges are removed when their parents are removed​.

Setup object cpusets/nodesets by OR'ing another object's sets​. For each defined cpuset or nodeset in src, allocate the corresponding set in dst and add src to it by OR'ing sets​.

This function is convenient between hwloc_topology_alloc_group_object() and hwloc_topology_insert_group_object()​. It builds the sets of the new Group that will be inserted as a new intermediate parent of several objects​.

Returns

Allocate a Group object to insert later with hwloc_topology_insert_group_object()​. This function returns a new Group object​.

The caller should (at least) initialize its sets before inserting the object in the topology, see hwloc_topology_insert_group_object()​. Or it may decide not to insert and just free the group object by calling hwloc_topology_free_group_object()​.

Returns

The allocated object on success​.

NULL on error​.

Note

If successfully inserted by hwloc_topology_insert_group_object(), the object will be freed when the entire topology is freed​. If insertion failed (e​.g​. NULL or empty CPU and node-sets), it is freed before returning the error​.

Change the sets of allowed PUs and NUMA nodes in the topology​. This function only works if the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was set on the topology​. It does not modify any object, it only changes the sets returned by hwloc_topology_get_allowed_cpuset() and hwloc_topology_get_allowed_nodeset()​.

It is notably useful when importing a topology from another process running in a different Linux Cgroup​.

flags must be set to one flag among hwloc_allow_flags_e​.

Returns

Note

Removing objects from a topology should rather be performed with hwloc_topology_restrict()​.

Free a group object allocated with hwloc_topology_alloc_group_object()​. This function is only useful if the group object was not given to hwloc_topology_insert_group_object() as planned​.

Note

topology must be the same as the one previously passed to hwloc_topology_alloc_group_object()​.

Returns

Add more structure to the topology by adding an intermediate Group​. The caller should first allocate a new Group object with hwloc_topology_alloc_group_object()​. Then it must setup at least one of its CPU or node sets to specify the final location of the Group in the topology​. Then the object can be passed to this function for actual insertion in the topology​.

The main use case for this function is to group a subset of siblings among the list of children below a single parent​. For instance, if grouping 4 cores out of a 8-core socket, the logical list of cores will be reordered so that the 4 grouped ones are consecutive​. Then, if needed, a new depth is added between the parent and those children, and the Group is inserted there​. At the end, the 4 grouped cores are now children of the Group, which replaces them as a child of the original parent​.

In practice, the grouped objects are specified through cpusets and/or nodesets, for instance using hwloc_obj_add_other_obj_sets() iteratively​. Hence it is possible to group objects that are not children of the same parent, for instance some PUs below the 4 cores in example above​. However this general case may fail if the expected Group conflicts with the existing hierarchy​. For instance if each core has two PUs, it is not possible to insert a Group containing a single PU of each core​.

To specify the objects to group, either the cpuset or nodeset field (or both, if compatible) must be set to a non-empty bitmap​. The complete_cpuset or complete_nodeset may be set instead if inserting with respect to the complete topology (including disallowed, offline or unknown objects)​. These sets cannot be larger than the current topology, or they would get restricted silently​. The core will setup the other sets after actual insertion​.

The subtype object attribute may be defined with hwloc_obj_set_subtype() to display something else than "Group" as the type name for this object in lstopo​. Custom name-value info pairs may be added with hwloc_obj_add_info() after insertion​.

The group dont_merge attribute may be set to 1 to prevent the hwloc core from ever merging this object with another hierarchically-identical object​. This is useful when the Group itself describes an important feature that cannot be exposed anywhere else in the hierarchy​.

The group kind attribute may be set to a high value such as 0xffffffff to tell hwloc that this new Group should always be discarded in favor of any existing Group with the same locality​.

Note

Inserting a group adds some locality information to the topology, hence the existing objects may get reordered (including PUs and NUMA nodes), and their logical indexes may change​.

If the insertion fails, the input group object is freed​.

If the group object should be discarded instead of inserted, it may be passed to hwloc_topology_free_group_object() instead​.

topology must be the same as the one previously passed to hwloc_topology_alloc_group_object()​.

Returns

The inserted object if it was properly inserted​.

An existing object if the Group was merged or discarded because the topology already contained an object at the same location (the Group did not add any hierarchy information)​.

NULL if the insertion failed because of conflicting sets in topology tree​.

NULL if Group objects are filtered-out of the topology (HWLOC_TYPE_FILTER_KEEP_NONE)​.

NULL if the object was discarded because no set was initialized in the Group before insert, or all of them were empty​.

Add a MISC object as a leaf of the topology​. A new MISC object will be created and inserted into the topology at the position given by parent​. It is appended to the list of existing Misc children, without ever adding any intermediate hierarchy level​. This is useful for annotating the topology without actually changing the hierarchy​.

name is supposed to be unique across all Misc objects in the topology​. It will be duplicated to setup the new object attributes​.

The new leaf object will not have any cpuset​.

The subtype object attribute may be defined with hwloc_obj_set_subtype() after successful insertion​.

Returns

the newly-created object

NULL on error​.

NULL if Misc objects are filtered-out of the topology (HWLOC_TYPE_FILTER_KEEP_NONE)​.

Note

If name contains some non-printable characters, they will be dropped when exporting to XML, see hwloc_topology_export_xml() in hwloc/export​.h​.

Refresh internal structures after topology modification​. Modifying the topology (by restricting, adding objects, modifying structures such as distances or memory attributes, etc​.) may cause some internal caches to become invalid​. These caches are automatically refreshed when accessed but this refreshing is not thread-safe​.

This function is not thread-safe either, but it is a good way to end a non-thread-safe phase of topology modification​. Once this refresh is done, multiple threads may concurrently consult the topology, objects, distances, attributes, etc​.

See also Thread Safety

Returns

Restrict the topology to the given CPU set or nodeset​. Topology topology is modified so as to remove all objects that are not included (or partially included) in the CPU set set​. All objects CPU and node sets are restricted accordingly​.

By default, set is a CPU set​. It means that the set of PUs in the topology is restricted​. Once some PUs got removed, their parents may also get removed recursively if they became child-less​.

If HWLOC_RESTRICT_FLAG_BYNODESET is passed in flags, set is considered a nodeset instead of a CPU set​. It means that the set of NUMA nodes in the topology is restricted (instead of PUs)​. Once some NUMA nodes got removed, their parents may also get removed recursively if they became child-less​.

flags is a OR'ed set of hwloc_restrict_flags_e​.

Note

Restricting the topology removes some locality information, hence the remaining objects may get reordered (including PUs and NUMA nodes), and their logical indexes may change​.

This call may not be reverted by restricting back to a larger set​. Once dropped during restriction, objects may not be brought back, except by loading another topology with hwloc_topology_load()​.

Returns