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).
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 --single Singlify the output to a single CPU.
69 --taskset Manipulate CPU set strings in the format recognized by the
71 taskset command-line program instead of hwloc-specific CPU
72 set string format.
73 -i <file>, --input <file>
75 Read topology from XML file <file> (instead of discovering
76 the topology on the local machine). If <file> is "-", the
77 standard input is used. XML support must have been compiled
78 in to hwloc for this option to be usable.
79 -i <directory>, --input <directory>
81 Read topology from the chroot specified by <directory>
82 (instead of discovering the topology on the local machine).
83 This option is generally only available on Linux. The chroot
84 was usually created by gathering another machine topology
85 with hwloc-gather-topology.
86 -i <specification>, --input <specification>
88 Simulate a fake hierarchy (instead of discovering the topol‐
89 ogy on the local machine). If <specification> is "node:2
90 pu:3", the topology will contain two NUMA nodes with 3 pro‐
91 cessing units in each of them.
92 --if <format>, --input-format <format>
94 Enforce the input in the given format, among xml, fsroot and
95 synthetic.
96 -v Verbose output.
98 --version Report version and exit.
100
102 hwloc-calc generates and manipulates CPU mask strings or objects. Both
103 input and output may be either objects (with physical or logical
104 indexes), CPU lists (with physical or logical indexes), or CPU mask
105 strings (always physically indexed).
106 If objects or CPU mask strings are given on the command-line, they are
108 combined and a single output is printed. If no object or CPU mask
109 strings are given on the command-line, the program will read the stan‐
110 dard input. It will combine multiple objects or CPU mask strings that
111 are given on the same line of the standard input line with spaces as
112 separators. Different input lines will be processed separately.
113 Command-line arguments and options are processed in order. For
115 instance, it means that changing the type of input indexes with --li or
116 changing the input topology with -i only affects the processing the
117 following arguments.
118 NOTE: It is highly recommended that you read the hwloc(7) overview page
120 before reading this man page. Most of the concepts described in
121 hwloc(7) directly apply to the hwloc-calc utility.
122
124 hwloc-calc's operation is best described through several examples.
125 To display the (physical) CPU mask corresponding to the second socket:
127 $ hwloc-calc socket:1
129 0x000000f0
130 To display the (physical) CPU mask corresponding to the third socket,
132 excluding its even numbered logical processors:
133 $ hwloc-calc socket:2 ~PU:even
135 0x00000c00
136 To combine two (physical) CPU masks:
138 $ hwloc-calc 0x0000ffff 0xff000000
140 0xff00ffff
141 To display the list of logical numbers of processors included in the
143 second socket:
144 $ hwloc-calc --intersect PU socket:1
146 4,5,6,7
147 To bind GNU OpenMP threads logically over the whole machine, we need to
149 use physical number output instead:
150 $ export GOMP_CPU_AFFINITY=`hwloc-calc --physical --intersect PU
152 machine:0`
153 $ echo $GOMP_CPU_AFFINITY
154 0,2,1,3
155 To display the list of NUMA nodes, by physical indexes, that intersect
157 a given (physical) CPU mask:
158 $ hwloc-calc --physical --intersect NUMAnode 0xf0f0f0f0
160 0,2
161 To display the physical index of a processor given by its logical
163 index:
164 $ hwloc-calc PU:2 --physical-output --intersect PU
166 3
167 To display the list of per-socket cores that intersect the input:
169 $ hwloc-calc 0x00003c00 --hierarchical socket.core
171 Socket:2.Core:1 Socket:3.Core:0
172 To display the (physical) CPU mask of the entire topology except the
174 third socket:
175 $ hwloc-calc all ~socket:3
177 0x0000f0ff
178 To combine both physical and logical indexes as input:
180 $ hwloc-calc PU:2 --physical-input PU:3
182 0x0000000c
183 To synthetize a set of cores into largest objects on a 2-node 2-socket
185 2-core machine:
186 $ hwloc-calc core:0 --largest
188 Core:0
189 $ hwloc-calc core:0-1 --largest
190 Socket:0
191 $ hwloc-calc core:4-7 --largest
192 NUMANode:1
193 $ hwloc-calc core:2-6 --largest
194 Socket:1 Socket:2 Core:6
195 $ hwloc-calc socket:2 --largest
196 Socket:2
197 $ hwloc-calc socket:2-3 --largest
198 NUMANode:1
199
202 Upon successful execution, hwloc-calc displays the (physical) CPU mask
203 string, (physical or logical) object list, or (physical or logical)
204 object number list. The return value is 0.
205 hwloc-calc will return nonzero if any kind of error occurs, such as
207 (but not limited to): failure to parse the command line.
208
210 hwloc(7), hwloc-gather-topology(1)
2111.2 Apr 14, 2011 HWLOC-CALC(1)