1HWLOC-CALC(1) hwloc HWLOC-CALC(1)
2
6 hwloc-calc - Operate on cpu mask strings and objects
7
9 hwloc-calc [options] <location1> [<location2> [...] ]
10 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
16 -p --physical
17 Use OS/physical indexes instead of logical indexes for both
18 input and output.
19 -l --logical
21 Use logical indexes instead of physical/OS indexes for both
22 input and output (default).
23 --pi --physical-input
25 Use OS/physical indexes instead of logical indexes for input.
26 --li --logical-input
28 Use logical indexes instead of physical/OS indexes for input
29 (default).
30 --po --physical-output
32 Use OS/physical indexes instead of logical indexes for out‐
33 put.
34 --lo --logical-output
36 Use logical indexes instead of physical/OS indexes for output
37 (default, except for cpusets which are always physical).
38 -n --nodeset
40 Interpret both input and output sets as nodesets instead of
41 CPU sets.
42 --no --nodeset-output
44 Report nodesets instead of CPU sets.
45 --ni --nodeset-input
47 Interpret input sets as nodesets instead of CPU sets.
48 -N --number-of <type|depth>
50 Report the number of objects of the given type or depth that
51 intersect the CPU set. This is convenient for finding how
52 many cores, NUMA nodes or PUs are available in a machine.
53 When combined with --nodeset or --nodeset-output, the nodeset
55 is considered instead of the CPU set for finding matching
56 objects. This is useful when reporting the output as a num‐
57 ber or set of NUMA nodes.
58 -I --intersect <type|depth>
60 Find the list of objects of the given type or depth that
61 intersect the CPU set and report the comma-separated list of
62 their indexes instead of the cpu mask string. This may be
63 used for determining the list of objects above or below the
64 input objects.
65 When combined with --physical, the list is convenient to pass
67 to external tools such as taskset or numactl --physcpubind or
68 --membind. This is different from --largest since the latter
69 requires that all reported objects are strictly included
70 inside the input objects.
71 When combined with --nodeset or --nodeset-output, the nodeset
73 is considered instead of the CPU set for finding matching
74 objects. This is useful when reporting the output as a num‐
75 ber or set of NUMA nodes.
76 -H --hierarchical <type1>.<type2>...
78 Find the list of objects of type <type2> that intersect the
79 CPU set and report the space-separated list of their hierar‐
80 chical indexes with respect to <type1>, <type2>, etc. For
81 instance, if package.core is given, the output would be Pack‐
82 age:1.Core:2 Package:2.Core:3 if the input contains the third
83 core of the second package and the fourth core of the third
84 package.
85 Only normal CPU-side object types may be used. NUMA nodes
87 cannot.
88 --largest Report (in a human readable format) the list of largest
90 objects which exactly include all input objects (by looking
91 at their CPU sets). None of these output objects intersect
92 each other, and the sum of them is exactly equivalent to the
93 input. No largest object is included in the input This is
94 different from --intersect where reported objects may not be
95 strictly included in the input.
96 --sep <sep>
98 Change the field separator in the output. By default, a
99 space is used to separate output objects (for instance when
100 --hierarchical or --largest is given) while a comma is used
101 to separate indexes (for instance when --intersect is given).
102 --single Singlify the output to a single CPU.
104 --no-smt, --no-smt=<N>
106 Only keep the first PU per core in the input locations. If
107 <N> is specified, keep the <N>-th instead, if any. PUs are
108 ordered by physical index during this filtering.
109 --taskset Display CPU set strings in the format recognized by the
111 taskset command-line program instead of hwloc-specific CPU
112 set string format. This option has no impact on the format
113 of input CPU set strings, both formats are always accepted.
114 --restrict <cpuset>
116 Restrict the topology to the given cpuset.
117 --disallowed
119 Include objects disallowed by administrative limitations.
120 -i <file>, --input <file>
122 Read topology from XML file <file> (instead of discovering
123 the topology on the local machine). If <file> is "-", the
124 standard input is used. XML support must have been compiled
125 in to hwloc for this option to be usable.
126 -i <directory>, --input <directory>
128 Read topology from <directory> instead of discovering the
129 topology of the local machine. On Linux, the directory may
130 contain the topology files gathered from another machine
131 topology with hwloc-gather-topology. On x86, the directory
132 may contain a cpuid dump gathered with hwloc-gather-cpuid.
133 -i <specification>, --input <specification>
135 Simulate a fake hierarchy (instead of discovering the topol‐
136 ogy on the local machine). If <specification> is "node:2
137 pu:3", the topology will contain two NUMA nodes with 3 pro‐
138 cessing units in each of them. The <specification> string
139 must end with a number of PUs.
140 --if <format>, --input-format <format>
142 Enforce the input in the given format, among xml, fsroot,
143 cpuid and synthetic.
144 -q --quiet
146 Hide non-fatal error messages. It mostly includes locations
147 pointing to non-existing objects.
148 -v --verbose
150 Verbose output.
151 --version Report version and exit.
153 -h --help Display help message and exit.
155
157 hwloc-calc generates and manipulates CPU mask strings or objects. Both
158 input and output may be either objects (with physical or logical
159 indexes), CPU lists (with physical or logical indexes), or CPU mask
160 strings (always physically indexed). Input location specification is
161 described in hwloc(7).
162 If objects or CPU mask strings are given on the command-line, they are
164 combined and a single output is printed. If no object or CPU mask
165 strings are given on the command-line, the program will read the stan‐
166 dard input. It will combine multiple objects or CPU mask strings that
167 are given on the same line of the standard input line with spaces as
168 separators. Different input lines will be processed separately.
169 Command-line arguments and options are processed in order. For
171 instance, it means that changing the type of input indexes with --li or
172 changing the input topology with -i only affects the processing the
173 following arguments.
174 NOTE: hwloc-calc cannot manipulate NUMA memory node sets. It only
176 manipulates CPU sets, which means it cannot do much about CPU-less NUMA
177 nodes.
178 NOTE: It is highly recommended that you read the hwloc(7) overview page
180 before reading this man page. Most of the concepts described in
181 hwloc(7) directly apply to the hwloc-calc utility.
182
184 hwloc-calc's operation is best described through several examples.
185 To display the (physical) CPU mask corresponding to the second package:
187 $ hwloc-calc package:1
189 0x000000f0
190 To display the (physical) CPU mask corresponding to the third pacakge,
192 excluding its even numbered logical processors:
193 $ hwloc-calc package:2 ~PU:even
195 0x00000c00
196 To combine two (physical) CPU masks:
198 $ hwloc-calc 0x0000ffff 0xff000000
200 0xff00ffff
201 To display the list of logical numbers of processors included in the
203 second package:
204 $ hwloc-calc --intersect PU package:1
206 4,5,6,7
207 To bind GNU OpenMP threads logically over the whole machine, we need to
209 use physical number output instead:
210 $ export GOMP_CPU_AFFINITY=`hwloc-calc --physical-output --inter‐
212 sect PU all`
213 $ echo $GOMP_CPU_AFFINITY
214 0,4,1,5,2,6,3,7
215 To display the list of NUMA nodes, by physical indexes, that intersect
217 a given (physical) CPU mask:
218 $ hwloc-calc --physical --intersect NUMAnode 0xf0f0f0f0
220 0,2
221 Converting object logical indexes (default) from/to physical/OS indexes
223 may be performed with --intersect combined with either --physical-out‐
224 put (logical to physical conversion) or --physical-input (physical to
225 logical):
226 $ hwloc-calc --physical-output PU:2 --intersect PU
228 3
229 $ hwloc-calc --physical-input PU:3 --intersect PU
230 2
231 One should add --nodeset when converting indexes of memory objects to
233 make sure a single NUMA node index is returned on platforms with het‐
234 erogeneous memory:
235 $ hwloc-calc --nodeset --physical-output node:2 --intersect node
237 3
238 $ hwloc-calc --nodeset --physical-input node:3 --intersect node
239 2
240 To display the set of CPUs near network interface eth0:
242 $ hwloc-calc os=eth0
244 0x00005555
245 To display the indexes of packages near PCI device whose bus ID is
247 0000:01:02.0:
248 $ hwloc-calc pci=0000:01:02.0 --intersect Package
250 1
251 To display the list of per-package cores that intersect the input:
253 $ hwloc-calc 0x00003c00 --hierarchical package.core
255 Package:2.Core:1 Package:3.Core:0
256 To display the (physical) CPU mask of the entire topology except the
258 third package:
259 $ hwloc-calc all ~package:3
261 0x0000f0ff
262 To combine both physical and logical indexes as input:
264 $ hwloc-calc PU:2 --physical-input PU:3
266 0x0000000c
267 To synthetize a set of cores into largest objects on a 2-node 2-package
269 2-core machine:
270 $ hwloc-calc core:0 --largest
272 Core:0
273 $ hwloc-calc core:0-1 --largest
274 Package:0
275 $ hwloc-calc core:4-7 --largest
276 NUMANode:1
277 $ hwloc-calc core:2-6 --largest
278 Package:1 Package:2 Core:6
279 $ hwloc-calc pack:2 --largest
280 Package:2
281 $ hwloc-calc package:2-3 --largest
282 NUMANode:1
283 To get the set of first threads of all cores:
285 $ hwloc-calc core:all.pu:0
287 $ hwloc-calc --no-smt all
288 This can also be very useful in order to make GNU OpenMP use exactly
290 one thread per core, and in logical core order:
291 $ export OMP_NUM_THREADS=`hwloc-calc --number-of core all`
293 $ echo $OMP_NUM_THREADS
294 4
295 $ export GOMP_CPU_AFFINITY=`hwloc-calc --physical-output --inter‐
296 sect PU --no-smt all`
297 $ echo $GOMP_CPU_AFFINITY
298 0,2,1,3
299
302 Upon successful execution, hwloc-calc displays the (physical) CPU mask
303 string, (physical or logical) object list, or (physical or logical)
304 object number list. The return value is 0.
305 hwloc-calc will return nonzero if any kind of error occurs, such as
307 (but not limited to): failure to parse the command line.
308
310 hwloc(7), lstopo(1), hwloc-info(1)
3112.2.0 Mar 30, 2020 HWLOC-CALC(1)