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
12 -p --physical
13 Use OS/physical indexes instead of logical indexes for both
14 input and output.
15 -l --logical
17 Use logical indexes instead of physical/OS indexes for both
18 input and output (default).
19 --pi --physical-input
21 Use OS/physical indexes instead of logical indexes for input.
22 --li --logical-input
24 Use logical indexes instead of physical/OS indexes for input
25 (default).
26 --po --physical-input
28 Use OS/physical indexes instead of logical indexes for out‐
29 put.
30 --lo --logical-output
32 Use logical indexes instead of physical/OS indexes for output
33 (default, except for cpusets which are always physical).
34 -N --number-of <type|depth>
36 Report the number of objects of the given type or depth that
37 intersect the CPU set. This is convenient for finding how
38 many cores, NUMA nodes or PUs are available in a machine.
39 -I --intersect <type|depth>
41 Find the list of objects of the given type or depth that
42 intersect the CPU set and report the comma-separated list of
43 their indexes instead of the cpu mask string. This may be
44 used for determining the list of objects above or below the
45 input objects. When combined with --physical, the list is
46 convenient to pass to external tools such as taskset or
47 numactl --physcpubind or --membind. This is different from
48 --largest since the latter requires that all reported objects
49 are strictly included inside the input objects.
50 -H --hierarchical <type1>.<type2>...
52 Find the list of objects of type <type2> that intersect the
53 CPU set and report the space-separated list of their hierar‐
54 chical indexes with respect to <type1>, <type2>, etc. For
55 instance, if socket.core is given, the output would be
56 Socket:1.Core:2 Socket:2.Core:3 if the input contains the
57 third core of the second socket and the fourth core of the
58 third socket.
59 --largest Report (in a human readable format) the list of largest
61 objects which exactly include all input objects. None of
62 these output objects intersect each other, and the sum of
63 them is exactly equivalent to the input. No largest object is
64 included in the input This is different from --intersect
65 where reported objects may not be strictly included in the
66 input.
67 --sep <sep>
69 Change the field separator in the output. By default, a
70 space is used to separate output objects (for instance when
71 --hierarchical or --largest is given) while a comma is used
72 to separate indexes (for instance when --intersect is given).
73 --single Singlify the output to a single CPU.
75 --taskset Display CPU set strings in the format recognized by the
77 taskset command-line program instead of hwloc-specific CPU
78 set string format. This option has no impact on the format
79 of input CPU set strings, both formats are always accepted.
80 --restrict <cpuset>
82 Restrict the topology to the given cpuset.
83 -i <file>, --input <file>
85 Read topology from XML file <file> (instead of discovering
86 the topology on the local machine). If <file> is "-", the
87 standard input is used. XML support must have been compiled
88 in to hwloc for this option to be usable.
89 -i <directory>, --input <directory>
91 Read topology from the chroot specified by <directory>
92 (instead of discovering the topology on the local machine).
93 This option is generally only available on Linux. The chroot
94 was usually created by gathering another machine topology
95 with hwloc-gather-topology.
96 -i <specification>, --input <specification>
98 Simulate a fake hierarchy (instead of discovering the topol‐
99 ogy on the local machine). If <specification> is "node:2
100 pu:3", the topology will contain two NUMA nodes with 3 pro‐
101 cessing units in each of them. The <specification> string
102 must end with a number of PUs.
103 --if <format>, --input-format <format>
105 Enforce the input in the given format, among xml, fsroot and
106 synthetic.
107 -v Verbose output.
109 --version Report version and exit.
111
113 hwloc-calc generates and manipulates CPU mask strings or objects. Both
114 input and output may be either objects (with physical or logical
115 indexes), CPU lists (with physical or logical indexes), or CPU mask
116 strings (always physically indexed).
117 If objects or CPU mask strings are given on the command-line, they are
119 combined and a single output is printed. If no object or CPU mask
120 strings are given on the command-line, the program will read the stan‐
121 dard input. It will combine multiple objects or CPU mask strings that
122 are given on the same line of the standard input line with spaces as
123 separators. Different input lines will be processed separately.
124 Command-line arguments and options are processed in order. For
126 instance, it means that changing the type of input indexes with --li or
127 changing the input topology with -i only affects the processing the
128 following arguments.
129 NOTE: It is highly recommended that you read the hwloc(7) overview page
131 before reading this man page. Most of the concepts described in
132 hwloc(7) directly apply to the hwloc-calc utility.
133
135 hwloc-calc's operation is best described through several examples.
136 To display the (physical) CPU mask corresponding to the second socket:
138 $ hwloc-calc socket:1
140 0x000000f0
141 To display the (physical) CPU mask corresponding to the third socket,
143 excluding its even numbered logical processors:
144 $ hwloc-calc socket:2 ~PU:even
146 0x00000c00
147 To combine two (physical) CPU masks:
149 $ hwloc-calc 0x0000ffff 0xff000000
151 0xff00ffff
152 To display the list of logical numbers of processors included in the
154 second socket:
155 $ hwloc-calc --intersect PU socket:1
157 4,5,6,7
158 To bind GNU OpenMP threads logically over the whole machine, we need to
160 use physical number output instead:
161 $ export GOMP_CPU_AFFINITY=`hwloc-calc --physical --intersect PU
163 machine:0`
164 $ echo $GOMP_CPU_AFFINITY
165 0,2,1,3
166 To display the list of NUMA nodes, by physical indexes, that intersect
168 a given (physical) CPU mask:
169 $ hwloc-calc --physical --intersect NUMAnode 0xf0f0f0f0
171 0,2
172 To display the physical index of a processor given by its logical
174 index:
175 $ hwloc-calc PU:2 --physical-output --intersect PU
177 3
178 To display the set of CPUs near network interface eth0:
180 $ hwloc-calc os=eth0
182 0x00005555
183 To display the indexes of sockets near PCI device whose bus ID is
185 0000:01:02.0:
186 $ hwloc-calc pci=0000:01:02.0 --intersect Socket
188 1
189 To display the list of per-socket cores that intersect the input:
191 $ hwloc-calc 0x00003c00 --hierarchical socket.core
193 Socket:2.Core:1 Socket:3.Core:0
194 To display the (physical) CPU mask of the entire topology except the
196 third socket:
197 $ hwloc-calc all ~socket:3
199 0x0000f0ff
200 To combine both physical and logical indexes as input:
202 $ hwloc-calc PU:2 --physical-input PU:3
204 0x0000000c
205 To synthetize a set of cores into largest objects on a 2-node 2-socket
207 2-core machine:
208 $ hwloc-calc core:0 --largest
210 Core:0
211 $ hwloc-calc core:0-1 --largest
212 Socket:0
213 $ hwloc-calc core:4-7 --largest
214 NUMANode:1
215 $ hwloc-calc core:2-6 --largest
216 Socket:1 Socket:2 Core:6
217 $ hwloc-calc socket:2 --largest
218 Socket:2
219 $ hwloc-calc socket:2-3 --largest
220 NUMANode:1
221 To get the set of first threads of all cores:
223 $ hwloc-calc core:all.pu:0
225
228 Upon successful execution, hwloc-calc displays the (physical) CPU mask
229 string, (physical or logical) object list, or (physical or logical)
230 object number list. The return value is 0.
231 hwloc-calc will return nonzero if any kind of error occurs, such as
233 (but not limited to): failure to parse the command line.
234
236 hwloc(7), hwloc-gather-topology(1)
2371.5 Jul 30, 2012 HWLOC-CALC(1)