NAME

       hwlocality_tinker

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)
       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)

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.

       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_BYNODESET.

       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.

   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.  See
       hwloc_topology_insert_group_object().

       The  subtype object attribute may be set 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 kind group attribute should be 0. The subkind group attribute may be set to identify multiple  Groups
       of the same level.

       It  is  recommended  not  to  set  any  other  object attribute before insertion, since the Group may get
       discarded during insertion.

       The object will be destroyed if passed to hwloc_topology_insert_group_object() without any set defined.

   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.

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

   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  group dont_merge attribute may be set to prevent the core from ever merging this object with another
       object hierarchically-identical.

       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).

       It  grouping  several  objects,  hwloc_obj_add_other_obj_sets()  is  an  easy way to build the Group sets
       iteratively.

       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.

       Returns:
           The inserted object if it was properly inserted.

           An existing object if the Group was discarded because the topology already contained an object at the
           same location (the Group did not add any locality information). Any name/info  key  pair  set  before
           inserting is appended to the existing object.

           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.

       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_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.

       If HWLOC_RESTRICT_FLAG_BYNODESET is passed in flags, set is considered a nodeset instead of a CPU set.

       flags is a OR'ed set of hwloc_restrict_flags_e.

       Note:
           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.

Version 2.1.0                                    Mon Sep 30 2019                            hwlocality_tinker(3)