1HWLOC-CALC(1)                        hwloc                       HWLOC-CALC(1)
2
3
4

NAME

6       hwloc-calc - Operate on cpu mask strings and objects
7

SYNOPSIS

9       hwloc-calc [options] <location1> [<location2> [...] ]
10
11       Note  that hwloc(7) provides a detailed explanation of the hwloc system
12       and of valid <location> formats; it should be read before reading  this
13       man page.
14

OPTIONS

16       -p --physical
17                 Use  OS/physical  indexes instead of logical indexes for both
18                 input and output.
19
20       -l --logical
21                 Use logical indexes instead of physical/OS indexes  for  both
22                 input and output (default).
23
24       --pi --physical-input
25                 Use OS/physical indexes instead of logical indexes for input.
26
27       --li --logical-input
28                 Use  logical indexes instead of physical/OS indexes for input
29                 (default).
30
31       --po --physical-output
32                 Use OS/physical indexes instead of logical indexes  for  out‐
33                 put.
34
35       --lo --logical-output
36                 Use logical indexes instead of physical/OS indexes for output
37                 (default, except for cpusets which are always physical).
38
39       -N --number-of <type|depth>
40                 Report the number of objects of the given type or depth  that
41                 intersect  the  CPU  set.  This is convenient for finding how
42                 many cores, NUMA nodes or PUs are available in a machine.
43
44       -I --intersect <type|depth>
45                 Find the list of objects of the  given  type  or  depth  that
46                 intersect  the CPU set and report the comma-separated list of
47                 their indexes instead of the cpu mask string.   This  may  be
48                 used  for  determining the list of objects above or below the
49                 input objects.  When combined with --physical,  the  list  is
50                 convenient  to  pass  to  external  tools  such as taskset or
51                 numactl --physcpubind or --membind.  This is  different  from
52                 --largest since the latter requires that all reported objects
53                 are strictly included inside the input objects.
54
55       -H --hierarchical <type1>.<type2>...
56                 Find the list of objects of type <type2> that  intersect  the
57                 CPU  set and report the space-separated list of their hierar‐
58                 chical indexes with respect to <type1>,  <type2>,  etc.   For
59                 instance, if package.core is given, the output would be Pack‐
60                 age:1.Core:2 Package:2.Core:3 if the input contains the third
61                 core  of  the second package and the fourth core of the third
62                 package.
63
64       --largest Report (in a human  readable  format)  the  list  of  largest
65                 objects  which  exactly  include  all input objects.  None of
66                 these output objects intersect each other,  and  the  sum  of
67                 them is exactly equivalent to the input. No largest object is
68                 included in the input  This  is  different  from  --intersect
69                 where  reported  objects  may not be strictly included in the
70                 input.
71
72       --sep <sep>
73                 Change the field separator in  the  output.   By  default,  a
74                 space  is  used to separate output objects (for instance when
75                 --hierarchical or --largest is given) while a comma  is  used
76                 to separate indexes (for instance when --intersect is given).
77
78       --single  Singlify the output to a single CPU.
79
80       --taskset Display  CPU  set  strings  in  the  format recognized by the
81                 taskset command-line program instead  of  hwloc-specific  CPU
82                 set  string  format.  This option has no impact on the format
83                 of input CPU set strings, both formats are always accepted.
84
85       --restrict <cpuset>
86                 Restrict the topology to the given cpuset.
87
88       --whole-system
89                 Do not consider administration limitations.
90
91       -i <file>, --input <file>
92                 Read topology from XML file <file>  (instead  of  discovering
93                 the  topology  on  the local machine).  If <file> is "-", the
94                 standard input is used.  XML support must have been  compiled
95                 in to hwloc for this option to be usable.
96
97       -i <directory>, --input <directory>
98                 Read  topology  from  the  chroot  specified  by  <directory>
99                 (instead of discovering the topology on the  local  machine).
100                 This option is generally only available on Linux.  The chroot
101                 was usually created by  gathering  another  machine  topology
102                 with hwloc-gather-topology.
103
104       -i <specification>, --input <specification>
105                 Simulate  a fake hierarchy (instead of discovering the topol‐
106                 ogy on the local  machine).  If  <specification>  is  "node:2
107                 pu:3",  the  topology will contain two NUMA nodes with 3 pro‐
108                 cessing units in each of them.   The  <specification>  string
109                 must end with a number of PUs.
110
111       --if <format>, --input-format <format>
112                 Enforce  the input in the given format, among xml, fsroot and
113                 synthetic.
114
115       -q --quiet
116                 Hide non-fatal error messages.  It mostly includes  locations
117                 pointing to non-existing objects.
118
119       -v --verbose
120                 Verbose output.
121
122       --version Report version and exit.
123

DESCRIPTION

125       hwloc-calc generates and manipulates CPU mask strings or objects.  Both
126       input and output may  be  either  objects  (with  physical  or  logical
127       indexes),  CPU  lists  (with  physical or logical indexes), or CPU mask
128       strings (always physically indexed).
129
130       If objects or CPU mask strings are given on the command-line, they  are
131       combined  and  a  single  output  is printed.  If no object or CPU mask
132       strings are given on the command-line, the program will read the  stan‐
133       dard  input.  It will combine multiple objects or CPU mask strings that
134       are given on the same line of the standard input line  with  spaces  as
135       separators.  Different input lines will be processed separately.
136
137       Command-line  arguments  and  options  are  processed  in  order.   For
138       instance, it means that changing the type of input indexes with --li or
139       changing  the  input  topology  with -i only affects the processing the
140       following arguments.
141
142       NOTE: hwloc-calc cannot manipulate NUMA  memory  node  sets.   It  only
143       manipulates CPU sets, which means it cannot do much about CPU-less NUMA
144       nodes.
145
146       NOTE: It is highly recommended that you read the hwloc(7) overview page
147       before  reading  this  man  page.   Most  of  the concepts described in
148       hwloc(7) directly apply to the hwloc-calc utility.
149

EXAMPLES

151       hwloc-calc's operation is best described through several examples.
152
153       To display the (physical) CPU mask corresponding to the second package:
154
155           $ hwloc-calc package:1
156           0x000000f0
157
158       To display the (physical) CPU mask corresponding to the third  pacakge,
159       excluding its even numbered logical processors:
160
161           $ hwloc-calc package:2 ~PU:even
162           0x00000c00
163
164       To combine two (physical) CPU masks:
165
166           $ hwloc-calc 0x0000ffff 0xff000000
167           0xff00ffff
168
169       To  display  the  list of logical numbers of processors included in the
170       second package:
171
172           $ hwloc-calc --intersect PU package:1
173           4,5,6,7
174
175       To bind GNU OpenMP threads logically over the whole machine, we need to
176       use physical number output instead:
177
178           $  export  GOMP_CPU_AFFINITY=`hwloc-calc --physical-output --inter‐
179       sect PU machine:0`
180           $ echo $GOMP_CPU_AFFINITY
181           0,4,1,5,2,6,3,7
182
183       To display the list of NUMA nodes, by physical indexes, that  intersect
184       a given (physical) CPU mask:
185
186           $ hwloc-calc --physical --intersect NUMAnode 0xf0f0f0f0
187           0,2
188
189       To  display  the  physical  index  of  a processor given by its logical
190       index:
191
192           $ hwloc-calc PU:2 --physical-output --intersect PU
193           3
194
195       To display the set of CPUs near network interface eth0:
196
197           $ hwloc-calc os=eth0
198           0x00005555
199
200       To display the indexes of packages near PCI  device  whose  bus  ID  is
201       0000:01:02.0:
202
203           $ hwloc-calc pci=0000:01:02.0 --intersect Package
204           1
205
206       To display the list of per-package cores that intersect the input:
207
208           $ hwloc-calc 0x00003c00 --hierarchical package.core
209           Package:2.Core:1 Package:3.Core:0
210
211       To  display  the  (physical) CPU mask of the entire topology except the
212       third package:
213
214           $ hwloc-calc all ~package:3
215           0x0000f0ff
216
217       To combine both physical and logical indexes as input:
218
219           $ hwloc-calc PU:2 --physical-input PU:3
220           0x0000000c
221
222       To synthetize a set of cores into largest objects on a 2-node 2-package
223       2-core machine:
224
225           $ hwloc-calc core:0 --largest
226           Core:0
227           $ hwloc-calc core:0-1 --largest
228           Package:0
229           $ hwloc-calc core:4-7 --largest
230           NUMANode:1
231           $ hwloc-calc core:2-6 --largest
232           Package:1 Package:2 Core:6
233           $ hwloc-calc pack:2 --largest
234           Package:2
235           $ hwloc-calc package:2-3 --largest
236           NUMANode:1
237
238       To get the set of first threads of all cores:
239
240           $ hwloc-calc core:all.pu:0
241
242       This  can  also  be very useful in order to make GNU OpenMP use exactly
243       one thread per core, and in logical core order:
244
245           $ export OMP_NUM_THREADS=`hwloc-calc --number-of core machine:0`
246           $ echo $OMP_NUM_THREADS
247           4
248           $ export GOMP_CPU_AFFINITY=`hwloc-calc  --physical-output  --inter‐
249       sect PU core:all.pu:0`
250           $ echo $GOMP_CPU_AFFINITY
251           0,2,1,3
252
253

RETURN VALUE

255       Upon  successful execution, hwloc-calc displays the (physical) CPU mask
256       string, (physical or logical) object list,  or  (physical  or  logical)
257       object number list.  The return value is 0.
258
259       hwloc-calc  will  return  nonzero  if any kind of error occurs, such as
260       (but not limited to): failure to parse the command line.
261

SEE ALSO

263       hwloc(7), lstopo(1), hwloc-info(1), hwloc-gather-topology(1)
264
265
266
267
2681.11.12                          Dec 13, 2018                    HWLOC-CALC(1)
Impressum