hwloc-annotate [options] <input.xml> <output.xml> <location> <mode> <annotation>
Note that hwloc(7) provides a detailed explanation of the hwloc system and of valid <location> formats; it should be read before reading this man page.
The annotation may be string info attributes. This is specified by the mode:
The first line of the pointed file must be a integer representing a distances kind as defined in hwloc/distances.h. The second line is the number of objects involved in the distances. The next lines contain one object each. The next lines contain one distance value each, or a single line may be given with a integer combination of format x*y or x*y*z.
Annotations may be added to one specific object in the topology, all of them, or all of a given type. This is specified by the location (see also EXAMPLES below). Multiple locations may be affected if they are specified between --. Objects may be specified as location tuples, as explained in hwloc(7). However hexadecimal bitmasks are not accepted since they may correspond to multiple objects.
NOTE: The existing annotations may be listed with hwloc-info.
NOTE: It is highly recommended that you read the hwloc(7) overview page before reading this man page. Most of the concepts described in hwloc(7) directly apply to the hwloc-annotate utility.
hwloc-annotate's operation is best described through several examples.
Add an info attribute to all Core and PU objects:
$ hwloc-annotate input.xml output.xml -- Core:all PU:all -- info infoname infovalue
Only add to all Core objects:
$ hwloc-annotate input.xml output.xml Core:all info infoname infovalue
Add a Misc object named "foobar" under the root object of the topology and modify the input XML directly:
$ hwloc-annotate file.xml file.xml root misc foobar
Add an info attribute to OS device #2 and #3:
$ hwloc-annotate input.xml output.xml os:2-3 info infoname infovalue
Change package objects to green with red text in the lstopo graphical output:
$ hwloc-annotate topo.xml topo.xml package:all info lstopoStyle "Background=#00ff00;Text=#ff0000"
$ lstopo -i topo.xml
hwloc-annotate will return nonzero if any kind of error occurs, such as (but not limited to) failure to parse the command line.