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

NAME

6       hwloc-annotate - Modify attributes in a XML topology
7

SYNOPSIS

9       hwloc-annotate [options] <input.xml> <output.xml> -- <location1> <loca‐
10       tion2> ... -- <mode> <annotation>
11
12       hwloc-annotate [options]  <input.xml>  <output.xml>  <location>  <mode>
13       <annotation>
14
15       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

OPTIONS

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
25       --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
29       --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
33       --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
37       --version Report version and exit.
38
39       -h --help Display help message and exit.
40

DESCRIPTION

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
46       The annotation may be string info attributes.  This is specified by the
47       mode:
48
49       info <name> <value>
50              Specifies  a  new  string  info attribute whose name is name and
51              value is value.
52
53       misc <name>
54              Specifies a new Misc object name.
55
56       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
60              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
67       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
72              If this attribute does not require specific initiators,  initia‐
73              tor is ignored.
74
75              Standard  attribute names are Capacity, Locality, Bandwidth, and
76              Latency.  All existing attributes in the input topology  may  be
77              listed with
78
79                  $ lstopo --memattrs -i input.xml
80
81
82       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
86              efficiency is an abstracted efficiency value that  will  enforce
87              ranking of kinds. It should be -1 if unknown.
88
89              flags must be 0 for now.
90
91              If  infoname  and  infovalue  are  given and non-empty, they are
92              added as info attributes to this kind of CPU.
93
94              See the function hwloc_cpukinds_register() for details.
95
96
97       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
103              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
112
113       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
118       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
125       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
134       distances-transform <name> remove-obj <obj>
135              Remove the given  object  from  the  distances  structure  named
136              <name>.
137
138       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
146              If <newtype> is "NULL", objects are removed from  the  distances
147              structure.
148
149
150       none   No  new annotation is added. This is useful when clearing exist‐
151              ing attributes.
152
153       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
160       NOTE: The existing annotations may be listed with hwloc-info.
161
162       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

EXAMPLES

167       hwloc-annotate's operation is best described through several examples.
168
169       Add an info attribute to all Core and PU objects:
170
171           $  hwloc-annotate  input.xml  output.xml -- Core:all PU:all -- info
172       infoname infovalue
173
174       Only add to all Core objects:
175
176           $ hwloc-annotate input.xml output.xml Core:all info infoname  info‐
177       value
178
179       Add  a Misc object named "foobar" under the root object of the topology
180       and modify the input XML directly:
181
182           $ hwloc-annotate file.xml file.xml root misc foobar
183
184       Add an info attribute to OS device #2 and #3:
185
186           $ hwloc-annotate input.xml output.xml os:2-3  info  infoname  info‐
187       value
188
189       Change  package  objects to green with red text in the lstopo graphical
190       output:
191
192           $ hwloc-annotate topo.xml  topo.xml  package:all  info  lstopoStyle
193       "Background=#00ff00;Text=#ff0000"
194           $ lstopo -i topo.xml
195
196       Set the memory attribute latency to 123 nanoseconds from the PUs in the
197       first package to the first NUMA node:
198
199           $  hwloc-annotate  topo.xml  topo.xml  numanode:0  memattr  Latency
200       $(hwloc-calc package:0) 123
201
202       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
206           $  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
211       Specify  that  PU 0-3 and PU 4-7 are of different kinds, and the latter
212       is more efficient:
213
214           $ 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
219       Replace NUMA nodes with Packages in the NUMALatency  distances  matrix,
220       when they have the exact same locality.
221
222           $  hwloc-annotate topo.xml topo.xml -- dummy -- distances-transform
223       NUMALatency replace-objs numanode packages
224
225       Remove NUMA node #3 from the NUMALatency distances matrix:
226
227           $ hwloc-annotate topo.xml topo.xml -- dummy --  distances-transform
228       NUMALatency remove-obj numa:3
229
230       Merge  all  NVSwitch  ports bandwidth information into a single port in
231       the NVLinkBandwidth matrix:
232
233           $ hwloc-annotate topo.xml topo.xml -- dummy --  distances-transform
234       NVLinkBandwidth merge-switch-ports
235
236       Apply a transitive closure to get inter-GPU bandwidth across NVSwitches
237       in the NVLinkBandwidth matrix:
238
239           $ hwloc-annotate topo.xml topo.xml -- dummy --  distances-transform
240       NVLinkBandwidth transitive-closure
241
242

RETURN VALUE

244       Upon  successful  execution, hwloc-annotate generates the output topol‐
245       ogy.  The return value is 0.
246
247       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

SEE ALSO

251       hwloc(7), lstopo(1), hwloc-info(1)
252
253
254
255
2562.5.0                            Jun 14, 2021                HWLOC-ANNOTATE(1)
Impressum