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 -h --help Display help message and exit.
38
40 hwloc-annotate loads a topology from a XML file, adds some annotations,
41 and export the resulting topology to another XML file. The input and
42 output files may be the same.
43 The annotation may be string info attributes. This is specified by the
45 mode:
46 info <name> <value>
48 Specifies a new string info attribute whose name is name and
49 value is value.
50 misc <name>
52 Specifies a new Misc object name.
53 memattr <name> <flags>
55 Register a new memory attribute whose name is name and flags is
56 flags. location is ignored in this mode.
57 Flags may be given as numeric values or as a comma-separated
59 list of flag names that are passed to hwloc_memattr_register().
60 Those names may be substrings of actual flag names as long as a
61 single one matches. For instance, a value of 1 (or higher)
62 means that highest values are considered best for this attri‐
63 bute.
64 memattr <name> <initiator> <value>
66 Set the memory attribute (whose name is name) from initiator
67 initiator (either an object or a CPU-set) to target NUMA node
68 location to value value.
69 If this attribute does not require specific initiators, initia‐
71 tor is ignored.
72 Standard attribute names are Capacity, Locality, Bandwidth, and
74 Latency. All existing attributes in the input topology may be
75 listed with
76 $ lstopo --memattrs -i input.xml
78 cpukind <cpuset> <efficiency> <flags> [<infoname> <infovalue>]
81 Specifies the kind of CPU for PUs listed in the given cpuset.
82 location is ignored in this mode.
83 efficiency is an abstracted efficiency value that will enforce
85 ranking of kinds. It should be -1 if unknown.
86 flags must be 0 for now.
88 If infoname and infovalue are given and non-empty, they are
90 added as info attributes to this kind of CPU.
91 See the function hwloc_cpukinds_register() for details.
93 distances <filename> [<flags>]
96 Specifies new distances to be added to the topology using speci‐
97 fications in <filename>. The optional flags (0 unless speci‐
98 fied) corresponds to the flags given to the function hwloc_dis‐
99 tances_set(). location is ignored in this mode.
100 The first line of the pointed file must be a integer represent‐
102 ing a distances kind as defined in hwloc/distances.h. The sec‐
103 ond line is the number of objects involved in the distances.
104 The next lines contain one object each. The next lines contain
105 one distance value each, or a single line may be given with a
106 integer combination of format x*y or x*y*z.
107 none No new annotation is added. This is useful when clearing exist‐
109 ing attributes.
110 Annotations may be added to one specific object in the topology, all of
112 them, or all of a given type. This is specified by the location (see
113 also EXAMPLES below). Multiple locations may be affected if they are
114 specified between --. Objects may be specified as location tuples, as
115 explained in hwloc(7). However hexadecimal bitmasks are not accepted
116 since they may correspond to multiple objects.
117 NOTE: The existing annotations may be listed with hwloc-info.
119 NOTE: It is highly recommended that you read the hwloc(7) overview page
121 before reading this man page. Most of the concepts described in
122 hwloc(7) directly apply to the hwloc-annotate utility.
123
125 hwloc-annotate's operation is best described through several examples.
126 Add an info attribute to all Core and PU objects:
128 $ hwloc-annotate input.xml output.xml -- Core:all PU:all -- info
130 infoname infovalue
131 Only add to all Core objects:
133 $ hwloc-annotate input.xml output.xml Core:all info infoname info‐
135 value
136 Add a Misc object named "foobar" under the root object of the topology
138 and modify the input XML directly:
139 $ hwloc-annotate file.xml file.xml root misc foobar
141 Add an info attribute to OS device #2 and #3:
143 $ hwloc-annotate input.xml output.xml os:2-3 info infoname info‐
145 value
146 Change package objects to green with red text in the lstopo graphical
148 output:
149 $ hwloc-annotate topo.xml topo.xml package:all info lstopoStyle
151 "Background=#00ff00;Text=#ff0000"
152 $ lstopo -i topo.xml
153 Set the memory attribute latency to 123 nanoseconds from the PUs in the
155 first package to the first NUMA node:
156 $ hwloc-annotate topo.xml topo.xml numanode:0 memattr Latency
158 $(hwloc-calc package:0) 123
159 Register a memory attribute MyApplicationPerformance (with flags speci‐
161 fying that it requires an initiator and reports higher values first)
162 and set its value for initiator CPU-set 0x11 to NUMA node #2 to 2345:
163 $ hwloc-annotate topo.xml topo.xml ignored memattr MyApplication‐
165 Performance need_init,higher
166 $ hwloc-annotate topo.xml topo.xml numanode:2 memattr MyApplica‐
167 tionPerformance 0x11 2345
168 Specify that PU 0-3 and PU 4-7 are of different kinds, and the latter
170 is more efficient:
171 $ hwloc-annotate topo.xml topo.xml dummy cpukind 0x0f 0 0 CoreType
173 Small
174 $ hwloc-annotate topo.xml topo.xml dummy cpukind 0xf0 1 0 CoreType
175 Big
176
178 Upon successful execution, hwloc-annotate generates the output topol‐
179 ogy. The return value is 0.
180 hwloc-annotate will return nonzero if any kind of error occurs, such as
182 (but not limited to) failure to parse the command line.
183
185 hwloc(7), lstopo(1), hwloc-info(1)
1862.4.1 Feb 11, 2021 HWLOC-ANNOTATE(1)