1HWLOC-ANNOTATE(1) hwloc HWLOC-ANNOTATE(1)
2
6 hwloc-annotate - Modify attributes in a XML topology
7
9 hwloc-annotate [options] <input.xml> <output.xml> -- <location1> <loca‐
10 tion2> ... -- <mode> <annotation>
11 hwloc-annotate [options] <input.xml> <output.xml> <location> <mode>
13 <annotation>
14 Note that hwloc(7) provides a detailed explanation of the hwloc system
16 and of valid <location> formats; it should be read before reading this
17 man page.
18
20 --ri Remove all info attributes that exist with the same name be‐
21 fore adding the new one. This option is only accepted in
22 "info" mode. If the info value is omitted, existing infos
23 are replaced with nothing.
24 --ci Clear the existing info attributes in the target objects be‐
26 fore annotating. If no new annotation has to be added after
27 clearing, mode should be set to none.
28 --cu Clear the existing userdata from the target objects. If
30 nothing else has to be performed after clearing, mode should
31 be set to none.
32 --cd Clear the existing distances from the topology. If nothing
34 else has to be performed after clearing, mode should be set
35 to none.
36 --version Report version and exit.
38 -h --help Display help message and exit.
40
42 hwloc-annotate loads a topology from a XML file, adds some annotations,
43 and export the resulting topology to another XML file. The input and
44 output files may be the same.
45 The annotation may be string info attributes. This is specified by the
47 mode:
48 info <name> <value>
50 Specifies a new string info attribute whose name is name and
51 value is value.
52 misc <name>
54 Specifies a new Misc object name.
55 memattr <name> <flags>
57 Register a new memory attribute whose name is name and flags is
58 flags. location is ignored in this mode.
59 Flags may be given as numeric values or as a comma-separated
61 list of flag names that are passed to hwloc_memattr_register().
62 Those names may be substrings of actual flag names as long as a
63 single one matches. For instance, a value of 1 (or higher)
64 means that highest values are considered best for this attri‐
65 bute.
66 memattr <name> <initiator> <value>
68 Set the memory attribute (whose name is name) from initiator
69 initiator (either an object or a CPU-set) to target NUMA node
70 location to value value.
71 If this attribute does not require specific initiators, initia‐
73 tor is ignored.
74 Standard attribute names are Capacity, Locality, Bandwidth, and
76 Latency. All existing attributes in the input topology may be
77 listed with
78 $ lstopo --memattrs -i input.xml
80 cpukind <cpuset> <efficiency> <flags> [<infoname> <infovalue>]
83 Specifies the kind of CPU for PUs listed in the given cpuset.
84 location is ignored in this mode.
85 efficiency is an abstracted efficiency value that will enforce
87 ranking of kinds. It should be -1 if unknown.
88 flags must be 0 for now.
90 If infoname and infovalue are given and non-empty, they are
92 added as info attributes to this kind of CPU.
93 See the function hwloc_cpukinds_register() for details.
95 distances <filename> [<flags>]
98 Specifies new distances to be added to the topology using speci‐
99 fications in <filename>. The optional flags (0 unless speci‐
100 fied) corresponds to the flags given to the function hwloc_dis‐
101 tances_set(). location is ignored in this mode.
102 The real first line of the pointed file must be a integer repre‐
104 senting a distances kind as defined in hwloc/distances.h. The
105 second line is the number of objects involved in the distances.
106 The next lines contain one object each. The next lines contain
107 one distance value each, or a single line may be given with a
108 integer combination of format x*y or x*y*z. An optional line
109 before all others may start with name= to specify the name of
110 the distances structure if any.
111 distances-transform <name> links
114 Transform a bandwidth distances structure named <name> into
115 links. See the documentation of HWLOC_DISTANCES_TRANSFORM_LINKS
116 in hwloc/distances.h for details.
117 distances-transform <name> merge-switch-ports
119 When switches appear in the matrix as different ports, merge all
120 of them into a single port for clarity. This currently only ap‐
121 plies to the NVLinkBandwidth matrix between NVIDIA GPUs. See
122 the documentation of HWLOC_DISTANCES_TRANS‐
123 FORM_MERGE_SWITCH_PORTS in hwloc/distances.h for details.
124 distances-transform <name> transitive-closure
126 If objects are connected across a switch, apply a transitive-
127 closure to report the bandwidth through that switch. This cur‐
128 rently only applies to the NVLinkBandwidth matrix between NVIDIA
129 GPUs. The bandwidth between all pairs of GPUs will be exposed
130 instead of bandwidths between single GPUs and single NVSwitch
131 ports. See the documentation of HWLOC_DISTANCES_TRANSFORM_TRAN‐
132 SITIVE_CLOSURE in hwloc/distances.h for details.
133 distances-transform <name> remove-obj <obj>
135 Remove the given object from the distances structure named
136 <name>.
137 distances-transform <name> replace-objs <oldtype> <newtype>
139 Replace objects of type <oldtype> in distances structure named
140 <name> with objects of type <newtype> with same locality. If
141 <oldtype> or <newtype> are not object types, they are assumed
142 subtypes of OS devices, e.g. "NVML" or "OpenCL". See the docu‐
143 mentation of hwloc_get_obj_with_same_locality() in
144 hwloc/helper.h for details.
145 If <newtype> is "NULL", objects are removed from the distances
147 structure.
148 none No new annotation is added. This is useful when clearing exist‐
151 ing attributes.
152 Annotations may be added to one specific object in the topology, all of
154 them, or all of a given type. This is specified by the location (see
155 also EXAMPLES below). Multiple locations may be affected if they are
156 specified between --. Objects may be specified as location tuples, as
157 explained in hwloc(7). However hexadecimal bitmasks are not accepted
158 since they may correspond to multiple objects.
159 NOTE: The existing annotations may be listed with hwloc-info.
161 NOTE: It is highly recommended that you read the hwloc(7) overview page
163 before reading this man page. Most of the concepts described in
164 hwloc(7) directly apply to the hwloc-annotate utility.
165
167 hwloc-annotate's operation is best described through several examples.
168 Add an info attribute to all Core and PU objects:
170 $ hwloc-annotate input.xml output.xml -- Core:all PU:all -- info
172 infoname infovalue
173 Only add to all Core objects:
175 $ hwloc-annotate input.xml output.xml Core:all info infoname info‐
177 value
178 Add a Misc object named "foobar" under the root object of the topology
180 and modify the input XML directly:
181 $ hwloc-annotate file.xml file.xml root misc foobar
183 Add an info attribute to OS device #2 and #3:
185 $ hwloc-annotate input.xml output.xml os:2-3 info infoname info‐
187 value
188 Change package objects to green with red text in the lstopo graphical
190 output:
191 $ hwloc-annotate topo.xml topo.xml package:all info lstopoStyle
193 "Background=#00ff00;Text=#ff0000"
194 $ lstopo -i topo.xml
195 Set the memory attribute latency to 123 nanoseconds from the PUs in the
197 first package to the first NUMA node:
198 $ hwloc-annotate topo.xml topo.xml numanode:0 memattr Latency
200 $(hwloc-calc package:0) 123
201 Register a memory attribute MyApplicationPerformance (with flags speci‐
203 fying that it requires an initiator and reports higher values first)
204 and set its value for initiator CPU-set 0x11 to NUMA node #2 to 2345:
205 $ hwloc-annotate topo.xml topo.xml ignored memattr MyApplication‐
207 Performance need_init,higher
208 $ hwloc-annotate topo.xml topo.xml numanode:2 memattr MyApplica‐
209 tionPerformance 0x11 2345
210 Specify that PU 0-3 and PU 4-7 are of different kinds, and the latter
212 is more efficient:
213 $ hwloc-annotate topo.xml topo.xml dummy cpukind 0x0f 0 0 CoreType
215 Small
216 $ hwloc-annotate topo.xml topo.xml dummy cpukind 0xf0 1 0 CoreType
217 Big
218 Replace NUMA nodes with Packages in the NUMALatency distances matrix,
220 when they have the exact same locality.
221 $ hwloc-annotate topo.xml topo.xml -- dummy -- distances-transform
223 NUMALatency replace-objs numanode packages
224 Remove NUMA node #3 from the NUMALatency distances matrix:
226 $ hwloc-annotate topo.xml topo.xml -- dummy -- distances-transform
228 NUMALatency remove-obj numa:3
229 Merge all NVSwitch ports bandwidth information into a single port in
231 the NVLinkBandwidth matrix:
232 $ hwloc-annotate topo.xml topo.xml -- dummy -- distances-transform
234 NVLinkBandwidth merge-switch-ports
235 Apply a transitive closure to get inter-GPU bandwidth across NVSwitches
237 in the NVLinkBandwidth matrix:
238 $ hwloc-annotate topo.xml topo.xml -- dummy -- distances-transform
240 NVLinkBandwidth transitive-closure
241
244 Upon successful execution, hwloc-annotate generates the output topol‐
245 ogy. The return value is 0.
246 hwloc-annotate will return nonzero if any kind of error occurs, such as
248 (but not limited to) failure to parse the command line.
249
251 hwloc(7), lstopo(1), hwloc-info(1)
2522.5.0 Jun 14, 2021 HWLOC-ANNOTATE(1)