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
21                 before 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
26                 before  annotating.   If  no  new  annotation has to be added
27                 after 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       -h --help Display help message and exit.
38

DESCRIPTION

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
44       The annotation may be string info attributes.  This is specified by the
45       mode:
46
47       info <name> <value>
48              Specifies  a  new  string  info attribute whose name is name and
49              value is value.
50
51       misc <name>
52              Specifies a new Misc object name.
53
54       distances <filename> [<flags>]
55              Specifies new distances to be added to the topology using speci‐
56              fications  in  <filename>.   The optional flags (0 unless speci‐
57              fied) corresponds to the flags given to the function  hwloc_dis‐
58              tances_set().  location is ignored in this mode.
59
60              The  first line of the pointed file must be a integer represent‐
61              ing a distances kind as defined in hwloc/distances.h.  The  sec‐
62              ond  line  is  the  number of objects involved in the distances.
63              The next lines contain one object each.  The next lines  contain
64              one  distance  value  each, or a single line may be given with a
65              integer combination of format x*y or x*y*z.
66
67       none   No new annotation is added. This is useful when clearing  exist‐
68              ing attributes.
69
70       Annotations may be added to one specific object in the topology, all of
71       them, or all of a given type.  This is specified by the  location  (see
72       also  EXAMPLES  below).  Multiple locations may be affected if they are
73       specified between --.  Objects may be specified as location tuples,  as
74       explained  in  hwloc(7).  However hexadecimal bitmasks are not accepted
75       since they may correspond to multiple objects.
76
77       NOTE: The existing annotations may be listed with hwloc-info.
78
79       NOTE: It is highly recommended that you read the hwloc(7) overview page
80       before  reading  this  man  page.   Most  of  the concepts described in
81       hwloc(7) directly apply to the hwloc-annotate utility.
82

EXAMPLES

84       hwloc-annotate's operation is best described through several examples.
85
86       Add an info attribute to all Core and PU objects:
87
88           $ hwloc-annotate input.xml output.xml -- Core:all  PU:all  --  info
89       infoname infovalue
90
91       Only add to all Core objects:
92
93           $  hwloc-annotate input.xml output.xml Core:all info infoname info‐
94       value
95
96       Add a Misc object named "foobar" under the root object of the  topology
97       and modify the input XML directly:
98
99           $ hwloc-annotate file.xml file.xml root misc foobar
100
101       Add an info attribute to OS device #2 and #3:
102
103           $  hwloc-annotate  input.xml  output.xml os:2-3 info infoname info‐
104       value
105
106       Change package objects to green with red text in the  lstopo  graphical
107       output:
108
109           $  hwloc-annotate  topo.xml  topo.xml  package:all info lstopoStyle
110       "Background=#00ff00;Text=#ff0000"
111           $ lstopo -i topo.xml
112

RETURN VALUE

114       Upon successful execution, hwloc-annotate generates the  output  topol‐
115       ogy.  The return value is 0.
116
117       hwloc-annotate will return nonzero if any kind of error occurs, such as
118       (but not limited to) failure to parse the command line.
119

SEE ALSO

121       hwloc(7), lstopo(1), hwloc-info(1)
122
123
124
125
1262.2.0                            Mar 30, 2020                HWLOC-ANNOTATE(1)
Impressum