1HWLOC-DISTANCES(1)                   hwloc                  HWLOC-DISTANCES(1)
2
3
4

NAME

6       hwloc-distances - Displays distance matrices
7

SYNOPSIS

9       hwloc-distances [options]
10

OPTIONS

12       -l --logical
13              Display  hwloc  logical indexes (default) instead of physical/OS
14              indexes.
15
16       -p --physical
17              Display OS/physical indexes instead of hwloc logical indexes.
18
19       -i <file>, --input <file>
20              Read topology from XML file <file> (instead of  discovering  the
21              topology  on the local machine).  If <file> is "-", the standard
22              input is used.  XML support must have been compiled in to  hwloc
23              for this option to be usable.
24
25       -i <directory>, --input <directory>
26              Read  topology from the chroot specified by <directory> (instead
27              of discovering the topology on the local machine).  This  option
28              is  generally  only  available on Linux.  The chroot was usually
29              created by gathering another machine topology with hwloc-gather-
30              topology.
31
32       -i <specification>, --input <specification>
33              Simulate  a  fake hierarchy (instead of discovering the topology
34              on the local machine). If <specification> is "node:2 pu:3",  the
35              topology  will contain two NUMA nodes with 3 processing units in
36              each of them.  The <specification> string must end with a number
37              of PUs.
38
39       --if <format>, --input-format <format>
40              Enforce  the  input  in  the given format, among xml, fsroot and
41              synthetic.
42
43       --restrict <cpuset>
44              Restrict the topology to the given cpuset.
45
46       --whole-system
47              Do not consider administration limitations.
48
49       -v --verbose
50              Verbose messages.
51
52       --version
53              Report version and exit.
54

DESCRIPTION

56       hwloc-distances displays also distance matrices attached to the  topol‐
57       ogy.   The  value  in the i-th row and j-th column is the distance from
58       object #i to object #j.
59
60       Unless defined by the user, matrices currently always contain  relative
61       latencies  between  NUMA nodes (which may or may not be accurate).  See
62       the definition of struct hwloc_distances_s in  include/hwloc.h  or  the
63       documentation for details.
64
65       These  latencies  are  normalized  to the latency of a local (non-NUMA)
66       access.  Hence 3.5 in row #i column #j  means  that  the  latency  from
67       cores  in NUMA node #i to memory in NUMA node #j is 3.5 higher than the
68       latency from cores to their local memory.  A breadth-first traversal of
69       the  topology  is performed starting from the root to find all distance
70       matrices.
71
72       NOTE: lstopo may also display distance matrices in its verbose  textual
73       output.   However  lstopo  only  prints  matrices that cover the entire
74       topology while hwloc-distances also displays matrices that ignore  part
75       of the topology.
76

EXAMPLES

78       On a quad-package opteron machine:
79
80           $ hwloc-distances
81           Latency matrix between 4 NUMANodes (depth 2) by logical indexes:
82             index     0     1     2     3
83                 0 1.000 1.600 2.200 2.200
84                 1 1.600 1.000 2.200 2.200
85                 2 2.200 2.200 1.000 1.600
86                 3 2.200 2.200 1.600 1.000
87

RETURN VALUE

89       Upon successful execution, hwloc-distances returns 0.
90
91       hwloc-distances  will  return nonzero if any kind of error occurs, such
92       as (but not limited to) failure to parse the command line.
93

SEE ALSO

95       hwloc(7), lstopo(1)
96
97
98
99
1001.11.12                          Dec 13, 2018               HWLOC-DISTANCES(1)