manpagez: man pages & more
man hwloc-annotate(1)
Home | html | info | man
hwloc-annotate(1)                    hwloc                   hwloc-annotate(1)




NAME

       hwloc-annotate - Modify attributes in a XML topology


SYNOPSIS

       hwloc-annotate [options] <input.xml> <output.xml> -- <location1> <loca-
       tion2> ... -- <mode> <annotation>

       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.


OPTIONS

       --ri      Remove  all  info  attributes  that  exist with the same name
                 before adding the new one.  This option is only  accepted  in
                 "info"  mode.   If  the info value is omitted, existing infos
                 are replaced with nothing.

       --ci      Clear the existing info  attributes  in  the  target  objects
                 before  annotating.   If  no  new  annotation has to be added
                 after clearing, mode should be set to none.

       --cu      Clear the existing userdata  from  the  target  objects.   If
                 nothing  else has to be performed after clearing, mode should
                 be set to none.

       --cd      Clear the existing distances from the topology.   If  nothing
                 else  has  to be performed after clearing, mode should be set
                 to none.

       -h --help Display help message and exit.


DESCRIPTION

       hwloc-annotate loads a topology from a XML file, adds some annotations,
       and  export  the resulting topology to another XML file.  The input and
       output files may be the same.

       The annotation may be string info attributes.  This is specified by the
       mode:

       info <name> <value>
              Specifies  a  new  string  info attribute whose name is name and
              value is value.

       misc <name>
              Specifies a new Misc object name.

       memattr <name> <i~ags>
              Register a new memory attribute whose name is name and flags  is
              flags.  location is ignored in this mode.

              Flags  may  be  given  as numeric values or as a comma-separated
              list of flag names that are passed to  hwloc_memattr_register().
              Those  names may be substrings of actual flag names as long as a
              single one matches.  For instance, a  value  of  1  (or  higher)
              means   that   highest  values  are  considered  best  for  this
              attribute.

       memattr <name> <initiator> <value>
              Set the memory attribute (whose name  is  name)  from  initiator
              initiator  (either  an  object or a CPU-set) to target NUMA node
              location to value value.

              If this attribute does not require specific initiators,  initia-
              tor is ignored.

              Standard  attribute names are Capacity, Locality, Bandwidth, and
              Latency.  All existing attributes in the input topology  may  be
              listed with

                  $ lstopo --memattrs -i input.xml


       cpukind <cpuset> <efficiency> <flags> [<infoname> <infovalue>]
              Specifies  the  kind  of CPU for PUs listed in the given cpuset.
              location is ignored in this mode.

              efficiency is an abstracted efficiency value that  will  enforce
              ranking of kinds. It should be -1 if unknown.

              flags must be 0 for now.

              If  infoname  and  infovalue  are  given and non-empty, they are
              added as info attributes to this kind of CPU.

              See the function hwloc_cpukinds_register() for details.


       distances <filename> [<flags>]
              Specifies new distances to be added to the topology using speci-
              fications  in  <filename>.   The optional flags (0 unless speci-
              fied) corresponds to the flags given to the function  hwloc_dis-
              tances_set().  location is ignored in this mode.

              The  first line of the pointed file must be a integer represent-
              ing a distances kind as defined in hwloc/distances.h.  The  sec-
              ond  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.

       none   No new annotation is added. This is useful when clearing  exist-
              ing attributes.

       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.


EXAMPLES

       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  info-
       value

       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  info-
       value

       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

       Set the memory attribute latency to 123 nanoseconds from the PUs in the
       first package to the first NUMA node:

           $  hwloc-annotate  topo.xml  topo.xml  numanode:0  memattr  Latency
       $(hwloc-calc package:0) 123

       Register a memory attribute MyApplicationPerformance (with flags speci-
       fying that it requires an initiator and reports  higher  values  first)
       and set its value for initiator CPU-set 0x11 to NUMA node #2 to 2345:

           $  hwloc-annotate  topo.xml topo.xml ignored memattr MyApplication-
       Performance need_init,higher
           $ hwloc-annotate topo.xml topo.xml  numanode:2  memattr  MyApplica-
       tionPerformance 0x11 2345

       Specify  that  PU 0-3 and PU 4-7 are of different kinds, and the latter
       is more efficient:

           $ hwloc-annotate topo.xml topo.xml dummy cpukind 0x0f 0 0  CoreType
       Small
           $  hwloc-annotate topo.xml topo.xml dummy cpukind 0xf0 1 0 CoreType
       Big


RETURN VALUE

       Upon successful execution, hwloc-annotate generates the  output  topol-
       ogy.  The return value is 0.

       hwloc-annotate will return nonzero if any kind of error occurs, such as
       (but not limited to) failure to parse the command line.


SEE ALSO

       hwloc(7), lstopo(1), hwloc-info(1)




2.4.0                            Nov 26, 2020                hwloc-annotate(1)

hwloc 2.4.0 - Generated Fri Feb 5 16:07:45 CST 2021
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.