Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
HWLOC-DISTRIB(1)		     hwloc		      HWLOC-DISTRIB(1)

NAME
       hwloc-distrib - Build a number of cpu masks distributed on the system

SYNOPSIS
       hwloc-distrib [options] _integer_

OPTIONS
       --single
	      Singlify each output to a	single CPU.

       --taskset
	      Show  CPU	 set  strings  in the format recognized	by the taskset
	      command-line program instead of hwloc-specific  CPU  set	string
	      format.

       -v --verbose
	      Verbose messages.

       -i <file>, --input <file>
	      Read  topology  from XML file <file> (instead of discovering the
	      topology on the local machine).  If <file> is "-", the  standard
	      input  is	used.  XML support must	have been compiled in to hwloc
	      for this option to be usable.

       -i <directory>, --input <directory>
	      Read topology from the chroot specified by <directory>  (instead
	      of  discovering the topology on the local	machine).  This	option
	      is generally only	available on Linux.  The  chroot  was  usually
	      created by gathering another machine topology with hwloc-gather-
	      topology.

       -i <specification>, --input <specification>
	      Simulate a fake hierarchy	(instead of discovering	 the  topology
	      on  the local machine). If <specification> is "node:2 pu:3", the
	      topology will contain two	NUMA nodes with	3 processing units  in
	      each of them.  The <specification> string	must end with a	number
	      of PUs.

       --if <format>, --input-format <format>
	      Enforce the input	in the given format,  among  xml,  fsroot  and
	      synthetic.

       --ignore	<type>
	      Ignore all objects of type <type>	in the topology.

       --from <type>
	      Distribute  starting  from  objects of the given type instead of
	      from the top of the topology hierarchy, i.e. ignoring the	struc-
	      ture given by objects above.

       --to <type>
	      Distribute  down to objects of the given type instead of down to
	      the bottom of the	topology hierarchy, i.e. ignoring  the	struc-
	      ture  given  by objects below.  This may be useful if some lati-
	      tude is desired for the binding, e.g.  just  bind	 several  pro-
	      cesses to	each package without specifying	a single core for each
	      of them.

       --at <type>
	      Distribute among objects of the given type.  This	is  equivalent
	      to specifying both --from	and --to at the	same time.

       --reverse
	      Distribute by starting with the last objects first, and singlify
	      CPU sets by keeping the last bit (instead	of the first bit).

       --restrict <cpuset>
	      Restrict the topology to the given cpuset.

       --whole-system
	      Do not consider administration limitations.

       --version
	      Report version and exit.

DESCRIPTION
       hwloc-distrib generates a series	of CPU masks corresponding to  a  dis-
       tribution  of  a	 given number of elements over the topology of the ma-
       chine. The distribution is done recursively from	the top	of the hierar-
       chy  (or	 from the level	specified by option --from) down to the	bottom
       of the hierarchy	(or down to the	level specified	by option --to,	or un-
       til only	one element remains), splitting	the number of elements at each
       encountered hierarchy level not ignored by options --ignore.

       This can	e.g. be	used to	distribute a set of  processes	hierarchically
       according  to  the  topology of a machine. These	masks can be used with
       hwloc-bind(1).

       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-bind utility.

EXAMPLES
       hwloc-distrib's operation is best described through several examples.

       If 4 processes have to be distributed across a machine, their CPU masks
       may be obtained with:

	   $ hwloc-distrib 4
	   0x0000000f
	   0x00000f00
	   0x000000f0
	   0x0000f000

       To distribute only among	the second package, the	topology should	be re-
       stricted:

	   $ hwloc-distrib --restrict $(hwloc-calc package:1) 4
	   0x00000010
	   0x00000020
	   0x00000040
	   0x00000080

       To get a	single processor of each CPU masks (prevent migration in  case
       of binding)

	   $ hwloc-distrib 4 --single
	   0x00000001
	   0x00000100
	   0x00000010
	   0x00001000

       Each output line	may be converted independently with hwloc-calc:

	   $ hwloc-distrib 4 --single |	hwloc-calc --taskset
	   0x1
	   0x100
	   0x10
	   0x1000

       To  convert  the	output into a list of processors that may be passed to
       dplace -c inside	a mpirun command line:

	   $ hwloc-distrib 4 --single |	xargs hwloc-calc --pulist
	   0,8,4,16

RETURN VALUE
       Upon successful execution, hwloc-distrib	displays one or	more CPU  mask
       strings.	 The return value is 0.

       hwloc-distrib  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), hwloc-gather-topology(1)

1.11.11				 Sep 02, 2018		      HWLOC-DISTRIB(1)

NAME | SYNOPSIS | OPTIONS | DESCRIPTION | EXAMPLES | RETURN VALUE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=hwloc-distrib&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help