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>  <location> <mode>
10       <annotation>
11
12       Note that hwloc(7) provides a detailed explanation of the hwloc  system
13       and  of valid <location> formats; it should be read before reading this
14       man page.
15

OPTIONS

17       --ri      Remove all info attributes that  exist  with  the  same  name
18                 before  adding  the new one.  This option is only accepted in
19                 "info" mode.  If the info value is  omitted,  existing  infos
20                 are replaced with nothing.
21
22       --ci      Clear  the  existing  info  attributes  in the target objects
23                 before annotating.  If no new  annotation  has  to  be  added
24                 after clearing, mode should be set to none.
25
26       --cu      Clear  the  existing  userdata  from  the target objects.  If
27                 nothing else has to be performed after clearing, mode  should
28                 be set to none.
29

DESCRIPTION

31       hwloc-annotate loads a topology from a XML file, adds some annotations,
32       and export the resulting topology to another XML file.  The  input  and
33       output files may be the same.
34
35       The annotation may be string info attributes.  This is specified by the
36       mode:
37
38       info <name> <value>
39              Specifies a new string info attribute whose  name  is  name  and
40              value is value.
41
42       misc <name>
43              Specifies a new Misc object name.
44
45       none   No  new annotation is added. This is useful when clearing exist‐
46              ing attributes.
47
48       Annotations may be added to one specific object in the topology, all of
49       them,  or  all of a given type.  This is specified by the location (see
50       also EXAMPLES below).  Objects may be specified as location tuples,  as
51       explained  in  hwloc(7).  However hexadecimal bitmasks are not accepted
52       since they may correspond to multiple objects.
53
54       NOTE: The existing annotations may be listed with hwloc-info.
55
56       NOTE: It is highly recommended that you read the hwloc(7) overview page
57       before  reading  this  man  page.   Most  of  the concepts described in
58       hwloc(7) directly apply to the hwloc-annotate utility.
59

EXAMPLES

61       hwloc-annotate's operation is best described through several examples.
62
63       Add an info attribute to all Core objects:
64
65           $ hwloc-annotate input.xml output.xml Core:all info infoname  info‐
66       value
67
68       Add  a Misc object named "foobar" under the root object of the topology
69       and modify the input XML directly:
70
71           $ hwloc-annotate file.xml file.xml root misc foobar
72
73       Add an info attribute to OS device #2 and #3:
74
75           $ hwloc-annotate input.xml output.xml os:2-3  info  infoname  info‐
76       value
77
78       Change  package  objects to green with red text in the lstopo graphical
79       output:
80
81           $ hwloc-annotate topo.xml  topo.xml  package:all  info  lstopoStyle
82       "Background=#00ff00;Text=#ff0000"
83           $ lstopo -i topo.xml
84

RETURN VALUE

86       Upon  successful  execution, hwloc-annotate generates the output topol‐
87       ogy.  The return value is 0.
88
89       hwloc-annotate will return nonzero if any kind of error occurs, such as
90       (but not limited to) failure to parse the command line.
91

SEE ALSO

93       hwloc(7), lstopo(1), hwloc-info(1)
94
95
96
97
981.11.12                          Dec 13, 2018                HWLOC-ANNOTATE(1)
Impressum