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 --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 -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 -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 --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 --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 --single Singlify the output to a single CPU.
79 --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 --restrict <cpuset>
86 Restrict the topology to the given cpuset.
87 --whole-system
89 Do not consider administration limitations.
90 -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 -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 -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 --if <format>, --input-format <format>
112 Enforce the input in the given format, among xml, fsroot and
113 synthetic.
114 -q --quiet
116 Hide non-fatal error messages. It mostly includes locations
117 pointing to non-existing objects.
118 -v --verbose
120 Verbose output.
121 --version Report version and exit.
123
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 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 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 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 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
151 hwloc-calc's operation is best described through several examples.
152 To display the (physical) CPU mask corresponding to the second package:
154 $ hwloc-calc package:1
156 0x000000f0
157 To display the (physical) CPU mask corresponding to the third pacakge,
159 excluding its even numbered logical processors:
160 $ hwloc-calc package:2 ~PU:even
162 0x00000c00
163 To combine two (physical) CPU masks:
165 $ hwloc-calc 0x0000ffff 0xff000000
167 0xff00ffff
168 To display the list of logical numbers of processors included in the
170 second package:
171 $ hwloc-calc --intersect PU package:1
173 4,5,6,7
174 To bind GNU OpenMP threads logically over the whole machine, we need to
176 use physical number output instead:
177 $ 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 To display the list of NUMA nodes, by physical indexes, that intersect
184 a given (physical) CPU mask:
185 $ hwloc-calc --physical --intersect NUMAnode 0xf0f0f0f0
187 0,2
188 To display the physical index of a processor given by its logical
190 index:
191 $ hwloc-calc PU:2 --physical-output --intersect PU
193 3
194 To display the set of CPUs near network interface eth0:
196 $ hwloc-calc os=eth0
198 0x00005555
199 To display the indexes of packages near PCI device whose bus ID is
201 0000:01:02.0:
202 $ hwloc-calc pci=0000:01:02.0 --intersect Package
204 1
205 To display the list of per-package cores that intersect the input:
207 $ hwloc-calc 0x00003c00 --hierarchical package.core
209 Package:2.Core:1 Package:3.Core:0
210 To display the (physical) CPU mask of the entire topology except the
212 third package:
213 $ hwloc-calc all ~package:3
215 0x0000f0ff
216 To combine both physical and logical indexes as input:
218 $ hwloc-calc PU:2 --physical-input PU:3
220 0x0000000c
221 To synthetize a set of cores into largest objects on a 2-node 2-package
223 2-core machine:
224 $ 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 To get the set of first threads of all cores:
239 $ hwloc-calc core:all.pu:0
241 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 $ 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
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 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
263 hwloc(7), lstopo(1), hwloc-info(1), hwloc-gather-topology(1)
2641.11.9 Jan 18, 2018 HWLOC-CALC(1)