hwlocality_tinker(3) Library Functions Manual hwlocality_tinker(3)
NAME
hwlocality_tinker - Modifying a loaded Topology
SYNOPSIS
Enumerations
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 }
Functions
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)
Detailed Description
Enumeration Type Documentation
enum hwloc_allow_flags_e
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.
enum hwloc_restrict_flags_e
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.
Function Documentation
int hwloc_obj_add_other_obj_sets (hwloc_obj_t dst, hwloc_obj_t src)
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
0 on success.
-1 with errno set to ENOMEM if some internal reallocation failed.
hwloc_obj_t hwloc_topology_alloc_group_object (hwloc_topology_t topology)
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.
int hwloc_topology_allow (hwloc_topology_t restrict topology,
hwloc_const_cpuset_t cpuset, hwloc_const_nodeset_t nodeset, unsigned
long flags)
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
0 on success, -1 on error.
Note
Removing objects from a topology should rather be performed with
hwloc_topology_restrict().
int hwloc_topology_free_group_object (hwloc_topology_t topology, hwloc_obj_t
group)
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
0 on success.
-1 on error, for instance if an invalid topology is given.
hwloc_obj_t hwloc_topology_insert_group_object (hwloc_topology_t topology,
hwloc_obj_t group)
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.
hwloc_obj_t hwloc_topology_insert_misc_object (hwloc_topology_t topology,
hwloc_obj_t parent, const char * name)
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.
int hwloc_topology_refresh (hwloc_topology_t topology)
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
0 on success.
-1 on error, for instance if some internal reallocation failed.
int hwloc_topology_restrict (hwloc_topology_t restrict topology,
hwloc_const_bitmap_t set, unsigned long flags)
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
0 on success.
-1 with errno set to EINVAL if the input set is invalid. The
topology is not modified in this case.
-1 with errno set to ENOMEM on failure to allocate internal data.
The topology is reinitialized in this case. It should be either
destroyed with hwloc_topology_destroy() or configured and loaded
again.
Author
Generated automatically by Doxygen for Hardware Locality (hwloc) from
the source code.
Hardware Locality (hwloc) Version 2.12.0 hwlocality_tinker(3)
Generated by dwww version 1.16 on Sat Oct 3 03:11:09 CEST 2026.