Provided by: hwloc-nox_1.11.2-3_amd64 bug

NAME

       hwloc - General information about hwloc ("hardware locality").

DESCRIPTION

       hwloc  provides  command line tools and a C API to obtain the hierarchical map of key computing elements,
       such as: NUMA memory nodes, shared caches, processor packages, processor cores, and processor  "threads".
       hwloc  also  gathers  various  attributes  such as cache and memory information, and is portable across a
       variety of different operating systems and platforms.

   Definitions
       Hwloc has some specific  definitions  for  terms  that  are  used  in  this  man  page  and  other  hwloc
       documentation.

       Hwloc CPU set:
            A  set  of  processors  included  in an hwloc object, expressed as a bitmask indexed by the physical
            numbers of the CPUs (as announced by the OS).  The hwloc definition of "CPU set" does not carry  any
            the same connotations as Linux's "CPU set" (e.g., process affinity, etc.).

       Linux CPU set:
            See  http://www.mjmwired.net/kernel/Documentation/cpusets.txt for a discussion of Linux CPU sets.  A
            super-short-ignoring-many-details description (taken from that page) is:

        "Cpusets provide a mechanism for assigning a set of CPUs and Memory
            Nodes to a set of tasks."

       Linux Cgroup:
            See http://www.mjmwired.net/kernel/Documentation/cgroups.txt  for  a  discussion  of  Linux  control
            groups.  A super-short-ignoring-many-details description (taken from that page) is:

        "Control Groups provide a mechanism for aggregating/partitioning sets
            of tasks, and all their future children, into hierarchical groups with specialized behaviour."

       To  be  clear,  hwloc  supports  all  of  the  above concepts.  It is simply worth noting that they are 3
       different things.

   Location Specification
       Locations refer to specific regions within a topology.  Before reading the rest of this man page, it  may
       be  useful to read lstopo(1) and/or run lstopo on your machine to see the reported topology tree.  Seeing
       and understanding a topology tree will definitely help in understanding the concepts that  are  discussed
       below.

       Locations can be specified in multiple ways:

       Tuples:   Tuples  of  hwloc  "objects"  and associated indexes can be specified in the form object:index.
                 Hwloc objects represent types of mapped items (e.g., packages, cores, etc.) in a topology tree;
                 indexes  are  non-negative  integers  that specify a unique physical object in a topology tree.
                 Both concepts are described in detail, below.

       Chaining multiple tuples together in the more general form
                 object1:index[.object2:index2[...]]  is permissable.  While the first tuple's object may appear
                 anywhere  in the topology, the Nth tuple's object must have a shallower topology depth than the
                 (N+1)th tuple's object.  Put simply: as you move right in a tuple chain, objects must go deeper
                 in  the topology tree.  When using logical indexes (which is the default), indexes specified in
                 chained tuples are relative to the scope of the parent object.  For example, "package:0.core:1"
                 refers  to  the  second  core  in the first package.  When using OS/physical indexes, the first
                 object matching the given index is used.

       Hex:      Locations can also be specified as hexidecimal bitmasks prefixed with  "0x".   Commas  must  be
                 used  to  separate  the  hex  digits into blocks of 8, such as "0xffc0140,0x00020110".  Leading
                 zeros in each block  do  not  need  to  be  specified.   For  example,  "0xffc0140,0x20110"  is
                 equivalent to the prior example, and "0x0000000f" is exactly equivalent to "0xf".  Intermediate
                 blocks of 8 digits that are all zeoro  can  be  left  empty;  "0xff0,,0x13"  is  equivalent  to
                 "0xff0,0x00000000,0x13".   If  the location is prefixed with the special string "0xf...f", then
                 all unspecified bits are set (as if the set were infinite).  For  example,  "0xf...f,0x1"  sets
                 both  the first bit and all bits starting with the 33rd.  The string "0xf...f" -- with no other
                 specified values -- sets all bits.

       I/O devices:
                 Locations may also be a PCI or OS object.  The corresponding value is the set of CPUs that  are
                 close  to  the  physical  device.   For  example,  "pci=02:03.1"  is  equivalent  to the set of
                 processors that are close to the hostbridge above PCI device with bus ID "02:03.1".   "os=eth0"
                 is equivalent to all processors close to the network interface whose software name is "eth0".

       Multiple  locations  can  be specified on the command lines (delimited by whitespace); the first token of
       the execution command is assumed to either follow  "--"  (if  specified)  or  the  first  token  that  is
       unrecognized as a location.

       By  default,  if multiple locations are specified, they are added, meaning that the binding will be wider
       in the sense that the process may run on more objects.

       If prefixed with "~", the given location will be  cleared  instead  of  added  to  the  current  list  of
       locations.  If prefixed with "x", the given location will be and'ed instead of added to the current list.
       If prefixed with "^", the given location will be xor'ed.

       "all" and "root" are special locations consisting in the root object in  tree.  It  contains  the  entire
       current  topology.   More complex operations may be performed by using hwloc-calc to compute intermediate
       values.

   Hwloc Objects
       Objects in tuples can be any of the following strings (listed from "biggest" to "smallest"):

       machine   A set of processors and memory.

       node      A NUMA node; a set of processors around memory which the processors can directly access.

       package   Typically a physical package or chip, that goes into a package, it is a grouping of one or more
                 processors.

       cache     A  cache  memory.  If  several  kinds  of  caches  exist  in  the system, a specific one may be
                 identified by its level (e.g. l1cache) and optionally by its type (e.g. l1icache).

       core      A single, physical processing unit which may still contain multiple logical processors, such as
                 hardware threads.

       pu        Short  for  processor  unit  (not  process!).   The smallest physical execution unit that hwloc
                 recognizes.  For example, there may be multiple PUs on a core (e.g., hardware threads).

       The additional system type can be used when several machines form an overall single system  image  (SSI),
       such as Kerrighed.

       I/O  devices  are  not  listed  here  since they are not identified using tuples as explained in Location
       Specification.

       Finally, note that an object can be denoted by its numeric "depth" in the topology graph.

   Hwloc Indexes
       Indexes are integer values that uniquely specify a given object of  a  specific  type.   Indexes  can  be
       expressed  either  as  logical values or physical values.  Most hwloc utilities accept logical indexes by
       default.  Passing --physical switches to physical/OS indexes.  Both  logical  and  physical  indexes  are
       described on this man page.

       Logical  indexes  are  relative  to  the object order in the output from the lstopo command.  They always
       start with 0 and increment by 1 for each successive object.

       Physical indexes are how the operating system refers to objects.  Note that while  physical  indexes  are
       non-negative integer values, the hardware and/or operating system may choose arbitrary values -- they may
       not start with 0, and successive objects may not have consecutive values.

       For example, if the first few lines of lstopo -p output are the following:

         Machine (47GB)
           NUMANode P#0 (24GB) + Package P#0 + L3 (12MB)
             L2 (256KB) + L1 (32KB) + Core P#0 + PU P#0
             L2 (256KB) + L1 (32KB) + Core P#1 + PU P#0
             L2 (256KB) + L1 (32KB) + Core P#2 + PU P#0
             L2 (256KB) + L1 (32KB) + Core P#8 + PU P#0
             L2 (256KB) + L1 (32KB) + Core P#9 + PU P#0
             L2 (256KB) + L1 (32KB) + Core P#10 + PU P#0
           NUMANode P#1 (24GB) + Package P#1 + L3 (12MB)
             L2 (256KB) + L1 (32KB) + Core P#0 + PU P#0
             L2 (256KB) + L1 (32KB) + Core P#1 + PU P#0
             L2 (256KB) + L1 (32KB) + Core P#2 + PU P#0
             L2 (256KB) + L1 (32KB) + Core P#8 + PU P#0
             L2 (256KB) + L1 (32KB) + Core P#9 + PU P#0
             L2 (256KB) + L1 (32KB) + Core P#10 + PU P#0

       In this example, the first core on the second package is logically number  6  (i.e.,  logically  the  7th
       core, starting from 0).  Its physical index is 0, but note that another core also has a physical index of
       0.  Hence, physical indexes may only be relevant within the scope of their parent (or set of  ancestors).
       In  this  example,  to  uniquely  identify  logical  core 6 with physical indexes, you must specify (at a
       minimum) both a package and a core: package 1, core 0.

       Index values, regardless of whether they are logical or physical, can be expressed in  several  different
       forms (where X, Y, and N are positive integers):

       X         The object with index value X.

       X-Y       All the objects with index values >= X and <= Y.

       X-        All the objects with index values >= X.

       X:N       N objects starting with index X, possibly wrapping around the end of the level.

       all       A special index value indicating all valid index values.

       odd       A special index value indicating all valid odd index values.

       even      A special index value indicating all valid even index values.

       REMEMBER:  hwloc's  command  line  tools  accept  logical  indexes  for  location values by default.  Use
       --physical and --logical to switch from one mode to another.

SEE ALSO

       Hwloc's command line  tool  documentation:  lstopo(1),  hwloc-bind(1),  hwloc-calc(1),  hwloc-distrib(1),
       hwloc-ps(1).

       Hwloc has many C API functions, each of which have their own man page.  Some top-level man pages are also
       provided,  grouping  similar  functions  together.   A  few  good  places   to   start   might   include:
       hwlocality_objects(3),       hwlocality_types(3),      hwlocality_creation(3),      hwlocality_cpuset(3),
       hwlocality_information(3), and hwlocality_binding(3).

       For a listing of all available hwloc man pages,  look  at  all  "hwloc*"  files  in  the  man1  and  man3
       directories.