Ubuntu Manpage: hwlocality_distances_get - Retrieve distances between objects

NAME

       hwlocality_distances_get - Retrieve distances between objects

SYNOPSIS

   Data Structures
       struct hwloc_distances_s

   Enumerations
       enum hwloc_distances_kind_e { HWLOC_DISTANCES_KIND_FROM_OS, HWLOC_DISTANCES_KIND_FROM_USER,
           HWLOC_DISTANCES_KIND_MEANS_LATENCY, HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH,
           HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES }
       enum hwloc_distances_transform_e { HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL,
           HWLOC_DISTANCES_TRANSFORM_LINKS, HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS,
           HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE }

   Functions
       int hwloc_distances_get (hwloc_topology_t topology, unsigned *nr, struct hwloc_distances_s **distances,
           unsigned long kind, unsigned long flags)
       int hwloc_distances_get_by_depth (hwloc_topology_t topology, int depth, unsigned *nr, struct
           hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
       int hwloc_distances_get_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned *nr, struct
           hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
       int hwloc_distances_get_by_name (hwloc_topology_t topology, const char *name, unsigned *nr, struct
           hwloc_distances_s **distances, unsigned long flags)
       const char * hwloc_distances_get_name (hwloc_topology_t topology, struct hwloc_distances_s *distances)
       void hwloc_distances_release (hwloc_topology_t topology, struct hwloc_distances_s *distances)
       int hwloc_distances_transform (hwloc_topology_t topology, struct hwloc_distances_s *distances, enum
           hwloc_distances_transform_e transform, void *transform_attr, unsigned long flags)

Detailed Description

Enumeration Type Documentation

enum hwloc_distances_kind_e
Kinds of distance matrices. The kind attribute of struct hwloc_distances_s is a OR'ed set of kinds.

Each distance matrix may have only one kind among HWLOC_DISTANCES_KIND_FROM_* specifying where distance
information comes from, and one kind among HWLOC_DISTANCES_KIND_MEANS_* specifying whether values are
latencies or bandwidths.

Enumerator

HWLOC_DISTANCES_KIND_FROM_OS
These distances were obtained from the operating system or hardware.

HWLOC_DISTANCES_KIND_FROM_USER
These distances were provided by the user.

HWLOC_DISTANCES_KIND_MEANS_LATENCY
Distance values are similar to latencies between objects. Values are smaller for closer objects,
hence minimal on the diagonal of the matrix (distance between an object and itself). It could also
be the number of network hops between objects, etc.

HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH
Distance values are similar to bandwidths between objects. Values are higher for closer objects,
hence maximal on the diagonal of the matrix (distance between an object and itself). Such values
are currently ignored for distance-based grouping.

HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES
This distances structure covers objects of different types. This may apply to the
'NVLinkBandwidth' structure in presence of a NVSwitch or POWER processor NVLink port.

enum hwloc_distances_transform_e
Transformations of distances structures.

Enumerator

HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL
Remove NULL objects from the distances structure. Every object that was replaced with NULL in the
objs array is removed and the values array is updated accordingly.

At least 2 objects must remain, otherwise hwloc_distances_transform() will return -1 with errno set to
EINVAL.

kind will be updated with or without HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES according to the remaining
objects.

HWLOC_DISTANCES_TRANSFORM_LINKS
Replace bandwidth values with a number of links. Usually all values will be either 0 (no link) or
1 (one link). However some matrices could get larger values if some pairs of peers are connected
by different numbers of links.

Values on the diagonal are set to 0.

This transformation only applies to bandwidth matrices.

HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS
Merge switches with multiple ports into a single object. This currently only applies to NVSwitches
where GPUs seem connected to different switch ports. Switch ports must be objects with subtype
'NVSwitch' as in the NVLinkBandwidth matrix.

This transformation will replace all ports with only the first one, now connected to all GPUs. Other
ports are removed by applying HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL internally.

HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE
Apply a transitive closure to the matrix to connect objects across switches. All pairs of GPUs
will be reported as directly connected instead GPUs being only connected to switches.

Switch ports must be objects with subtype 'NVSwitch' as in the NVLinkBandwidth matrix.

Function Documentation

   int  hwloc_distances_get  (hwloc_topology_t  topology,  unsigned * nr, struct hwloc_distances_s ** distances,
       unsigned long kind, unsigned long flags)
       Retrieve distance matrices. Retrieve distance matrices from the topology into the distances array.

       flags is currently unused, should be 0.

       kind  serves  as  a  filter.  If  0,  all  distance  matrices  are  returned.   If   it   contains   some
       HWLOC_DISTANCES_KIND_FROM_*,  only  distance matrices whose kind matches one of these are returned. If it
       contains some HWLOC_DISTANCES_KIND_MEANS_*, only distance matrices whose kind matches one  of  these  are
       returned.

       On  input,  nr  points  to the number of distance matrices that may be stored in distances. On output, nr
       points to the number of distance matrices that were actually found, even if  some  of  them  couldn't  be
       stored  in  distances.  Distance  matrices  that  couldn't  be stored are ignored, but the function still
       returns success (0). The caller may find out by comparing the value pointed by nr before  and  after  the
       function call.

       Each  distance  matrix  returned  in  the  distances  array  should  be  released  by  the  caller  using
       hwloc_distances_release().

       Returns
           0 on success, -1 on error.

   int  hwloc_distances_get_by_depth  (hwloc_topology_t   topology,   int   depth,   unsigned   *   nr,   struct
       hwloc_distances_s ** distances, unsigned long kind, unsigned long flags)
       Retrieve   distance   matrices   for   object   at  a  specific  depth  in  the  topology.  Identical  to
       hwloc_distances_get() with the additional depth filter.

       Returns
           0 on success, -1 on error.

   int hwloc_distances_get_by_name (hwloc_topology_t  topology,  const  char  *  name,  unsigned  *  nr,  struct
       hwloc_distances_s ** distances, unsigned long flags)
       Retrieve  a  distance  matrix with the given name. Usually only one distances structure may match a given
       name.

       The name of the most common structure  is  'NUMALatency'.  Others  include  'XGMIBandwidth',  'XGMIHops',
       'XeLinkBandwidth', and 'NVLinkBandwidth'.

       Returns
           0 on success, -1 on error.

   int  hwloc_distances_get_by_type  (hwloc_topology_t  topology,  hwloc_obj_type_t  type, unsigned * nr, struct
       hwloc_distances_s ** distances, unsigned long kind, unsigned long flags)
       Retrieve distance matrices for object of a specific type. Identical  to  hwloc_distances_get()  with  the
       additional type filter.

       Returns
           0 on success, -1 on error.

   const char * hwloc_distances_get_name (hwloc_topology_t topology, struct hwloc_distances_s * distances)
       Get  a  description  of  what  a  distances  structure contains. For instance 'NUMALatency' for hardware-
       provided NUMA distances (ACPI SLIT), or NULL if unknown.

       Returns
           the constant string with the name of the distance structure.

       Note
           The returned name should not be freed by the caller, it belongs to the hwloc library.

   void hwloc_distances_release (hwloc_topology_t topology, struct hwloc_distances_s * distances)
       Release a distance matrix structure previously returned by hwloc_distances_get().

       Note
           This function is not required if the structure is removed with hwloc_distances_release_remove().

   int  hwloc_distances_transform  (hwloc_topology_t  topology,  struct  hwloc_distances_s  *  distances,   enum
       hwloc_distances_transform_e transform, void * transform_attr, unsigned long flags)
       Apply  a  transformation  to  a  distances  structure.  Modify  a distances structure that was previously
       obtained with hwloc_distances_get() or one of its variants.

       This modifies the local copy of the distances structures but does not modify  the  distances  information
       stored inside the topology (retrieved by another call to hwloc_distances_get() or exported to XML). To do
       so,  one should add a new distances structure with same name, kind, objects and values (see Add distances
       between objects) and then remove this old one with hwloc_distances_release_remove().

       transform must be one of the transformations listed in hwloc_distances_transform_e.

       These transformations may modify the contents of the objs or values arrays.

       transform_attr must be NULL for now.

       flags must be 0 for now.

       Returns
           0 on success, -1 on error for instance if flags are invalid.

       Note
           Objects  in  distances   array   objs   may   be   directly   modified   in   place   without   using
           hwloc_distances_transform(). One may use hwloc_get_obj_with_same_locality() to easily convert between
           similar objects of different types.

Author

       Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code.

Hardware Locality (hwloc)                        Version 2.12.0                      hwlocality_distances_get(3)