1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
.TH "hwlocality_distances_get" 3 "Version 2.12.0" "Hardware Locality (hwloc)" \" -*- nroff -*-
.ad l
.nh
.SH NAME
hwlocality_distances_get \- Retrieve distances between objects
.SH SYNOPSIS
.br
.PP
.SS "Data Structures"
.in +1c
.ti -1c
.RI "struct \fBhwloc_distances_s\fP"
.br
.in -1c
.SS "Enumerations"
.in +1c
.ti -1c
.RI "enum \fBhwloc_distances_kind_e\fP { \fBHWLOC_DISTANCES_KIND_FROM_OS\fP, \fBHWLOC_DISTANCES_KIND_FROM_USER\fP, \fBHWLOC_DISTANCES_KIND_MEANS_LATENCY\fP, \fBHWLOC_DISTANCES_KIND_MEANS_BANDWIDTH\fP, \fBHWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES\fP }"
.br
.ti -1c
.RI "enum \fBhwloc_distances_transform_e\fP { \fBHWLOC_DISTANCES_TRANSFORM_REMOVE_NULL\fP, \fBHWLOC_DISTANCES_TRANSFORM_LINKS\fP, \fBHWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS\fP, \fBHWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE\fP }"
.br
.in -1c
.SS "Functions"
.in +1c
.ti -1c
.RI "int \fBhwloc_distances_get\fP (\fBhwloc_topology_t\fP topology, unsigned *nr, struct \fBhwloc_distances_s\fP **distances, unsigned long kind, unsigned long flags)"
.br
.ti -1c
.RI "int \fBhwloc_distances_get_by_depth\fP (\fBhwloc_topology_t\fP topology, int depth, unsigned *nr, struct \fBhwloc_distances_s\fP **distances, unsigned long kind, unsigned long flags)"
.br
.ti -1c
.RI "int \fBhwloc_distances_get_by_type\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_obj_type_t\fP type, unsigned *nr, struct \fBhwloc_distances_s\fP **distances, unsigned long kind, unsigned long flags)"
.br
.ti -1c
.RI "int \fBhwloc_distances_get_by_name\fP (\fBhwloc_topology_t\fP topology, const char *name, unsigned *nr, struct \fBhwloc_distances_s\fP **distances, unsigned long flags)"
.br
.ti -1c
.RI "const char * \fBhwloc_distances_get_name\fP (\fBhwloc_topology_t\fP topology, struct \fBhwloc_distances_s\fP *distances)"
.br
.ti -1c
.RI "void \fBhwloc_distances_release\fP (\fBhwloc_topology_t\fP topology, struct \fBhwloc_distances_s\fP *distances)"
.br
.ti -1c
.RI "int \fBhwloc_distances_transform\fP (\fBhwloc_topology_t\fP topology, struct \fBhwloc_distances_s\fP *distances, enum \fBhwloc_distances_transform_e\fP transform, void *transform_attr, unsigned long flags)"
.br
.in -1c
.SH "Detailed Description"
.PP
.SH "Enumeration Type Documentation"
.PP
.SS "enum \fBhwloc_distances_kind_e\fP"
.PP
Kinds of distance matrices\&. The \fCkind\fP attribute of struct \fBhwloc_distances_s\fP is a OR'ed set of kinds\&.
.PP
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\&.
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIHWLOC_DISTANCES_KIND_FROM_OS \fP\fP
These distances were obtained from the operating system or hardware\&.
.TP
\fB\fIHWLOC_DISTANCES_KIND_FROM_USER \fP\fP
These distances were provided by the user\&.
.TP
\fB\fIHWLOC_DISTANCES_KIND_MEANS_LATENCY \fP\fP
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\&.
.TP
\fB\fIHWLOC_DISTANCES_KIND_MEANS_BANDWIDTH \fP\fP
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\&.
.TP
\fB\fIHWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES \fP\fP
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\&.
.SS "enum \fBhwloc_distances_transform_e\fP"
.PP
Transformations of distances structures\&.
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIHWLOC_DISTANCES_TRANSFORM_REMOVE_NULL \fP\fP
Remove \fCNULL\fP objects from the distances structure\&. Every object that was replaced with \fCNULL\fP in the \fCobjs\fP array is removed and the \fCvalues\fP array is updated accordingly\&.
.PP
At least \fC2\fP objects must remain, otherwise \fBhwloc_distances_transform()\fP will return \fC-1\fP with \fCerrno\fP set to \fCEINVAL\fP\&.
.PP
\fCkind\fP will be updated with or without \fBHWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES\fP according to the remaining objects\&.
.TP
\fB\fIHWLOC_DISTANCES_TRANSFORM_LINKS \fP\fP
Replace bandwidth values with a number of links\&. Usually all values will be either \fC0\fP (no link) or \fC1\fP (one link)\&. However some matrices could get larger values if some pairs of peers are connected by different numbers of links\&.
.PP
Values on the diagonal are set to \fC0\fP\&.
.PP
This transformation only applies to bandwidth matrices\&.
.TP
\fB\fIHWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS \fP\fP
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\&.
.PP
This transformation will replace all ports with only the first one, now connected to all GPUs\&. Other ports are removed by applying \fBHWLOC_DISTANCES_TRANSFORM_REMOVE_NULL\fP internally\&.
.TP
\fB\fIHWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE \fP\fP
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\&.
.PP
Switch ports must be objects with subtype 'NVSwitch' as in the NVLinkBandwidth matrix\&.
.SH "Function Documentation"
.PP
.SS "int hwloc_distances_get (\fBhwloc_topology_t\fP topology, unsigned * nr, struct \fBhwloc_distances_s\fP ** distances, unsigned long kind, unsigned long flags)"
.PP
Retrieve distance matrices\&. Retrieve distance matrices from the topology into the \fCdistances\fP array\&.
.PP
\fCflags\fP is currently unused, should be \fC0\fP\&.
.PP
\fCkind\fP serves as a filter\&. If \fC0\fP, 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\&.
.PP
On input, \fCnr\fP points to the number of distance matrices that may be stored in \fCdistances\fP\&. On output, \fCnr\fP points to the number of distance matrices that were actually found, even if some of them couldn't be stored in \fCdistances\fP\&. Distance matrices that couldn't be stored are ignored, but the function still returns success (\fC0\fP)\&. The caller may find out by comparing the value pointed by \fCnr\fP before and after the function call\&.
.PP
Each distance matrix returned in the \fCdistances\fP array should be released by the caller using \fBhwloc_distances_release()\fP\&.
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error\&.
.RE
.PP
.SS "int hwloc_distances_get_by_depth (\fBhwloc_topology_t\fP topology, int depth, unsigned * nr, struct \fBhwloc_distances_s\fP ** distances, unsigned long kind, unsigned long flags)"
.PP
Retrieve distance matrices for object at a specific depth in the topology\&. Identical to \fBhwloc_distances_get()\fP with the additional \fCdepth\fP filter\&.
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error\&.
.RE
.PP
.SS "int hwloc_distances_get_by_name (\fBhwloc_topology_t\fP topology, const char * name, unsigned * nr, struct \fBhwloc_distances_s\fP ** distances, unsigned long flags)"
.PP
Retrieve a distance matrix with the given name\&. Usually only one distances structure may match a given name\&.
.PP
The name of the most common structure is 'NUMALatency'\&. Others include 'XGMIBandwidth', 'XGMIHops', 'XeLinkBandwidth', and 'NVLinkBandwidth'\&.
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error\&.
.RE
.PP
.SS "int hwloc_distances_get_by_type (\fBhwloc_topology_t\fP topology, \fBhwloc_obj_type_t\fP type, unsigned * nr, struct \fBhwloc_distances_s\fP ** distances, unsigned long kind, unsigned long flags)"
.PP
Retrieve distance matrices for object of a specific type\&. Identical to \fBhwloc_distances_get()\fP with the additional \fCtype\fP filter\&.
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error\&.
.RE
.PP
.SS "const char * hwloc_distances_get_name (\fBhwloc_topology_t\fP topology, struct \fBhwloc_distances_s\fP * distances)"
.PP
Get a description of what a distances structure contains\&. For instance 'NUMALatency' for hardware-provided NUMA distances (ACPI SLIT), or \fCNULL\fP if unknown\&.
.PP
\fBReturns\fP
.RS 4
the constant string with the name of the distance structure\&.
.RE
.PP
\fBNote\fP
.RS 4
The returned name should not be freed by the caller, it belongs to the hwloc library\&.
.RE
.PP
.SS "void hwloc_distances_release (\fBhwloc_topology_t\fP topology, struct \fBhwloc_distances_s\fP * distances)"
.PP
Release a distance matrix structure previously returned by \fBhwloc_distances_get()\fP\&.
.PP
\fBNote\fP
.RS 4
This function is not required if the structure is removed with \fBhwloc_distances_release_remove()\fP\&.
.RE
.PP
.SS "int hwloc_distances_transform (\fBhwloc_topology_t\fP topology, struct \fBhwloc_distances_s\fP * distances, enum \fBhwloc_distances_transform_e\fP transform, void * transform_attr, unsigned long flags)"
.PP
Apply a transformation to a distances structure\&. Modify a distances structure that was previously obtained with \fBhwloc_distances_get()\fP or one of its variants\&.
.PP
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 \fBhwloc_distances_get()\fP or exported to XML)\&. To do so, one should add a new distances structure with same name, kind, objects and values (see \fBAdd distances between objects\fP) and then remove this old one with \fBhwloc_distances_release_remove()\fP\&.
.PP
\fCtransform\fP must be one of the transformations listed in \fBhwloc_distances_transform_e\fP\&.
.PP
These transformations may modify the contents of the \fCobjs\fP or \fCvalues\fP arrays\&.
.PP
\fCtransform_attr\fP must be \fCNULL\fP for now\&.
.PP
\fCflags\fP must be \fC0\fP for now\&.
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error for instance if flags are invalid\&.
.RE
.PP
\fBNote\fP
.RS 4
Objects in distances array \fCobjs\fP may be directly modified in place without using \fBhwloc_distances_transform()\fP\&. One may use \fBhwloc_get_obj_with_same_locality()\fP to easily convert between similar objects of different types\&.
.RE
.PP
.SH "Author"
.PP
Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.
|
