1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Hardware Locality (hwloc): Hardware Locality</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<td id="projectalign">
<div id="projectname">Hardware Locality (hwloc)<span id="projectnumber"> 2.12.2</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.8 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(function() {
initMenu('',false,false,'search.php','Search');
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div><div class="header">
<div class="headertitle"><div class="title">Hardware Locality </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1 class="sub">Portable abstraction of hierarchical architectures for high-performance computing</h1>
<hr />
<p> <br />
</p>
<h1><a class="anchor" id="toc"></a>
Table of Contents</h1>
<ul>
<li>
Introduction <ul>
<li>
<a class="el" href="index.html#overview">hwloc Overview</a> </li>
<li>
<a class="el" href="index.html#cli_examples">Command-line Examples</a> </li>
<li>
<a class="el" href="index.html#interface">Programming Interface</a> </li>
<li>
<a class="el" href="index.html#bugs">Questions and Bugs</a> </li>
<li>
<a class="el" href="index.html#history">History / Credits</a> </li>
</ul>
</li>
<li>
Chapters <ul>
<li>
<a class="el" href="a00365.html">Installation</a> </li>
<li>
<a class="el" href="a00366.html">Compiling software on top of hwloc's C API</a> </li>
<li>
<a class="el" href="a00367.html">Terms and Definitions</a> </li>
<li>
<a class="el" href="a00368.html">Command-Line Tools</a> </li>
<li>
<a class="el" href="a00369.html">Environment Variables</a> </li>
<li>
<a class="el" href="a00370.html">CPU and Memory Binding Overview</a> </li>
<li>
<a class="el" href="a00371.html">I/O Devices</a> </li>
<li>
<a class="el" href="a00372.html">Miscellaneous objects</a> </li>
<li>
<a class="el" href="a00373.html">Object attributes</a> </li>
<li>
<a class="el" href="a00374.html">Topology Attributes: Distances, Memory Attributes and CPU Kinds</a> </li>
<li>
<a class="el" href="a00375.html">Heterogeneous Memory</a> </li>
<li>
<a class="el" href="a00376.html">Importing and exporting topologies from/to XML files</a> </li>
<li>
<a class="el" href="a00377.html">Synthetic topologies</a> </li>
<li>
<a class="el" href="a00378.html">Interoperability With Other Software</a> </li>
<li>
<a class="el" href="a00379.html">Thread Safety</a> </li>
<li>
<a class="el" href="a00380.html">Components and plugins</a> </li>
<li>
<a class="el" href="a00381.html">Embedding hwloc in Other Software</a> </li>
<li>
<a class="el" href="a00382.html">Frequently Asked Questions (FAQ)</a> </li>
<li>
<a class="el" href="a00383.html">Upgrading to the hwloc 2.0 API</a> </li>
</ul>
</li>
</ul>
<p>
This page contains all the <i>Introduction</i> sections.
Chapters are also available from the <i>Related Pages</i> tab above.
</p>
<h1><a class="anchor" id="overview"></a>
hwloc Overview</h1>
<p>The Hardware Locality (hwloc) software project aims at easing the process of discovering hardware resources in parallel architectures. It offers command-line tools and a C API for consulting these resources, their locality, attributes, and interconnection. hwloc primarily aims at helping high-performance computing (HPC) applications, but is also applicable to any project seeking to exploit code and/or data locality on modern computing platforms.</p>
<p>hwloc provides command line tools and a C API to obtain the hierarchical map of key computing elements within a node, such as: NUMA memory nodes, shared caches, processor packages, dies and cores, processing units (logical processors or "threads") and even I/O devices. hwloc also gathers various attributes such as cache and memory information, and is portable across a variety of different operating systems and platforms.</p>
<p>hwloc primarily aims at helping high-performance computing (HPC) applications, but is also applicable to any project seeking to exploit code and/or data locality on modern computing platforms.</p>
<p>hwloc supports the following operating systems:</p>
<ul>
<li>
Linux (with knowledge of cgroups and cpusets, memory targets/initiators, etc.) on all supported hardware, including Intel Xeon Phi, ScaleMP vSMP, and NumaScale NumaConnect. </li>
<li>
Solaris (with support for processor sets and logical domains) </li>
<li>
AIX </li>
<li>
Darwin / OS X </li>
<li>
FreeBSD and its variants (such as kFreeBSD/GNU) </li>
<li>
NetBSD </li>
<li>
HP-UX </li>
<li>
Microsoft Windows </li>
<li>
IBM BlueGene/Q Compute Node Kernel (CNK) </li>
</ul>
<p>Since it uses standard Operating System information, hwloc's support is mostly independant from the processor type (x86, powerpc, ...) and just relies on the Operating System support. The main exception is BSD operating systems (NetBSD, FreeBSD, etc.) because they do not provide support topology information, hence hwloc uses an x86-only CPUID-based backend (which can be used for other OSes too, see the <a class="el" href="a00380.html">Components and plugins</a> section).</p>
<p>To check whether hwloc works on a particular machine, just try to build it and run <code>lstopo</code> or <code>lstopo-no-graphics</code>. If some things do not look right (e.g. bogus or missing cache information), see <a class="el" href="index.html#bugs">Questions and Bugs</a>.</p>
<p>hwloc only reports the number of processors on unsupported operating systems; no topology information is available.</p>
<p>For development and debugging purposes, hwloc also offers the ability to work on "fake" topologies:</p>
<ul>
<li>
Symmetrical tree of resources generated from a list of level arities, see <a class="el" href="a00377.html">Synthetic topologies</a>. </li>
<li>
Remote machine simulation through the gathering of topology as XML files, see <a class="el" href="a00376.html">Importing and exporting topologies from/to XML files</a>. </li>
</ul>
<p>hwloc can display the topology in a human-readable format, either in graphical mode (X11), or by exporting in one of several different formats, including: plain text, LaTeX tikzpicture, PDF, PNG, and FIG (see <a class="el" href="index.html#cli_examples">Command-line Examples</a> below). Note that some of the export formats require additional support libraries.</p>
<p>hwloc offers a programming interface for manipulating topologies and objects. It also brings a powerful CPU bitmap API that is used to describe topology objects location on physical/logical processors. See the <a class="el" href="index.html#interface">Programming Interface</a> below. It may also be used to binding applications onto certain cores or memory nodes. Several utility programs are also provided to ease command-line manipulation of topology objects, binding of processes, and so on.</p>
<p>Bindings for several other languages are available from the <a href="https://www.open-mpi.org/projects/hwloc/#language_bindings">project website</a>.</p>
<h1><a class="anchor" id="cli_examples"></a>
Command-line Examples</h1>
<p>On a 4-package 2-core machine with hyper-threading, the <code>lstopo</code> tool may show the following graphical output:</p>
<div class="image">
<img src="dudley.png" alt=""/>
</div>
<p>Here's the equivalent output in textual form:</p>
<pre class="fragment">Machine
NUMANode L#0 (P#0)
Package L#0 + L3 L#0 (4096KB)
L2 L#0 (1024KB) + L1 L#0 (16KB) + Core L#0
PU L#0 (P#0)
PU L#1 (P#8)
L2 L#1 (1024KB) + L1 L#1 (16KB) + Core L#1
PU L#2 (P#4)
PU L#3 (P#12)
Package L#1 + L3 L#1 (4096KB)
L2 L#2 (1024KB) + L1 L#2 (16KB) + Core L#2
PU L#4 (P#1)
PU L#5 (P#9)
L2 L#3 (1024KB) + L1 L#3 (16KB) + Core L#3
PU L#6 (P#5)
PU L#7 (P#13)
Package L#2 + L3 L#2 (4096KB)
L2 L#4 (1024KB) + L1 L#4 (16KB) + Core L#4
PU L#8 (P#2)
PU L#9 (P#10)
L2 L#5 (1024KB) + L1 L#5 (16KB) + Core L#5
PU L#10 (P#6)
PU L#11 (P#14)
Package L#3 + L3 L#3 (4096KB)
L2 L#6 (1024KB) + L1 L#6 (16KB) + Core L#6
PU L#12 (P#3)
PU L#13 (P#11)
L2 L#7 (1024KB) + L1 L#7 (16KB) + Core L#7
PU L#14 (P#7)
PU L#15 (P#15)
</pre><p>Note that there is also an equivalent output in XML that is meant for exporting/importing topologies but it is hardly readable to human-beings (see <a class="el" href="a00376.html">Importing and exporting topologies from/to XML files</a> for details).</p>
<p>On a 4-package 2-core Opteron NUMA machine (with two core cores disallowed by the administrator), the <code>lstopo</code> tool may show the following graphical output (with <code>--disallowed</code> for displaying disallowed objects):</p>
<div class="image">
<img src="hagrid.png" alt=""/>
</div>
<p>Here's the equivalent output in textual form:</p>
<pre class="fragment">Machine (32GB total)
Package L#0
NUMANode L#0 (P#0 8190MB)
L2 L#0 (1024KB) + L1 L#0 (64KB) + Core L#0 + PU L#0 (P#0)
L2 L#1 (1024KB) + L1 L#1 (64KB) + Core L#1 + PU L#1 (P#1)
Package L#1
NUMANode L#1 (P#1 8192MB)
L2 L#2 (1024KB) + L1 L#2 (64KB) + Core L#2 + PU L#2 (P#2)
L2 L#3 (1024KB) + L1 L#3 (64KB) + Core L#3 + PU L#3 (P#3)
Package L#2
NUMANode L#2 (P#2 8192MB)
L2 L#4 (1024KB) + L1 L#4 (64KB) + Core L#4 + PU L#4 (P#4)
L2 L#5 (1024KB) + L1 L#5 (64KB) + Core L#5 + PU L#5 (P#5)
Package L#3
NUMANode L#3 (P#3 8192MB)
L2 L#6 (1024KB) + L1 L#6 (64KB) + Core L#6 + PU L#6 (P#6)
L2 L#7 (1024KB) + L1 L#7 (64KB) + Core L#7 + PU L#7 (P#7)
</pre><p>On a 2-package quad-core Xeon (pre-Nehalem, with 2 dual-core dies into each package):</p>
<div class="image">
<img src="emmett.png" alt=""/>
</div>
<p>Here's the same output in textual form:</p>
<pre class="fragment">Machine (total 16GB)
NUMANode L#0 (P#0 16GB)
Package L#0
L2 L#0 (4096KB)
L1 L#0 (32KB) + Core L#0 + PU L#0 (P#0)
L1 L#1 (32KB) + Core L#1 + PU L#1 (P#4)
L2 L#1 (4096KB)
L1 L#2 (32KB) + Core L#2 + PU L#2 (P#2)
L1 L#3 (32KB) + Core L#3 + PU L#3 (P#6)
Package L#1
L2 L#2 (4096KB)
L1 L#4 (32KB) + Core L#4 + PU L#4 (P#1)
L1 L#5 (32KB) + Core L#5 + PU L#5 (P#5)
L2 L#3 (4096KB)
L1 L#6 (32KB) + Core L#6 + PU L#6 (P#3)
L1 L#7 (32KB) + Core L#7 + PU L#7 (P#7)
</pre><h1><a class="anchor" id="interface"></a>
Programming Interface</h1>
<p>The basic interface is available in <a class="el" href="a00095_source.html">hwloc.h</a>. Some higher-level functions are available in <a class="el" href="a00098_source.html">hwloc/helper.h</a> to reduce the need to manually manipulate objects and follow links between them. Documentation for all these is provided later in this document. Developers may also want to look at hwloc/inlines.h which contains the actual inline code of some <a class="el" href="a00095_source.html">hwloc.h</a> routines, and at this document, which provides good higher-level topology traversal examples.</p>
<p>To precisely define the vocabulary used by hwloc, a <a class="el" href="a00367.html">Terms and Definitions</a> section is available and should probably be read first.</p>
<p>Each hwloc object contains a cpuset describing the list of processing units that it contains. These bitmaps may be used for <a class="el" href="a00170.html">CPU binding</a> and <a class="el" href="a00171.html">Memory binding</a>. hwloc offers an extensive bitmap manipulation interface in <a class="el" href="a00101_source.html">hwloc/bitmap.h</a>.</p>
<p>Moreover, hwloc also comes with additional helpers for interoperability with several commonly used environments. See the <a class="el" href="a00378.html">Interoperability With Other Software</a> section for details.</p>
<p>The complete API documentation is available in a full set of HTML pages, man pages, and self-contained PDF files (formatted for both both US letter and A4 formats) in the source tarball in doc/doxygen-doc/.</p>
<p><b>NOTE:</b> If you are building the documentation from a Git clone, you will need to have Doxygen and pdflatex installed – the documentation will be built during the normal "make" process. The documentation is installed during "make install" to $prefix/share/doc/hwloc/ and your systems default man page tree (under $prefix, of course).</p>
<h2><a class="anchor" id="portability"></a>
Portability</h2>
<p>Operating System have varying support for CPU and memory binding, e.g. while some Operating Systems provide interfaces for all kinds of CPU and memory bindings, some others provide only interfaces for a limited number of kinds of CPU and memory binding, and some do not provide any binding interface at all. Hwloc's binding functions would then simply return the ENOSYS error (Function not implemented), meaning that the underlying Operating System does not provide any interface for them. <a class="el" href="a00170.html">CPU binding</a> and <a class="el" href="a00171.html">Memory binding</a> provide more information on which hwloc binding functions should be preferred because interfaces for them are usually available on the supported Operating Systems.</p>
<p>Similarly, the ability of reporting topology information varies from one platform to another. As shown in <a class="el" href="index.html#cli_examples">Command-line Examples</a>, hwloc can obtain information on a wide variety of hardware topologies. However, some platforms and/or operating system versions will only report a subset of this information. For example, on an PPC64-based system with 8 cores (each with 2 hardware threads) running a default 2.6.18-based kernel from RHEL 5.4, hwloc is only able to glean information about NUMA nodes and processor units (PUs). No information about caches, packages, or cores is available.</p>
<p>Here's the graphical output from lstopo on this platform when Simultaneous Multi-Threading (SMT) is enabled:</p>
<div class="image">
<img src="ppc64-with-smt.png" alt=""/>
</div>
<p>And here's the graphical output from lstopo on this platform when SMT is disabled:</p>
<div class="image">
<img src="ppc64-without-smt.png" alt=""/>
</div>
<p>Notice that hwloc only sees half the PUs when SMT is disabled. PU L#6, for example, seems to change location from NUMA node #0 to #1. In reality, no PUs "moved" – they were simply re-numbered when hwloc only saw half as many (see also Logical index in <a class="el" href="a00367.html#termsanddefs_indexes">Indexes and Sets</a>). Hence, PU L#6 in the SMT-disabled picture probably corresponds to PU L#12 in the SMT-enabled picture.</p>
<p>This same "PUs have disappeared" effect can be seen on other platforms – even platforms / OSs that provide much more information than the above PPC64 system. This is an unfortunate side-effect of how operating systems report information to hwloc.</p>
<p>Note that upgrading the Linux kernel on the same PPC64 system mentioned above to 2.6.34, hwloc is able to discover all the topology information. The following picture shows the entire topology layout when SMT is enabled:</p>
<div class="image">
<img src="ppc64-full-with-smt.png" alt=""/>
</div>
<p>Developers using the hwloc API or XML output for portable applications should therefore be extremely careful to not make any assumptions about the structure of data that is returned. For example, per the above reported PPC topology, it is not safe to assume that PUs will always be descendants of cores.</p>
<p>Additionally, future hardware may insert new topology elements that are not available in this version of hwloc. Long-lived applications that are meant to span multiple different hardware platforms should also be careful about making structure assumptions. For example, a new element may someday exist between a core and a PU.</p>
<h2><a class="anchor" id="interface_example"></a>
API Example</h2>
<p>The following small C example (available in the source tree as ``doc/examples/hwloc-hello.c'') prints the topology of the machine and performs some thread and memory binding. More examples are available in the doc/examples/ directory of the source tree.</p>
<div class="fragment"><div class="line"><span class="comment">/* Example hwloc API program.</span></div>
<div class="line"><span class="comment"> *</span></div>
<div class="line"><span class="comment"> * See other examples under doc/examples/ in the source tree</span></div>
<div class="line"><span class="comment"> * for more details.</span></div>
<div class="line"><span class="comment"> *</span></div>
<div class="line"><span class="comment"> * Copyright © 2009-2016 Inria. All rights reserved.</span></div>
<div class="line"><span class="comment"> * Copyright © 2009-2011 Université Bordeaux</span></div>
<div class="line"><span class="comment"> * Copyright © 2009-2010 Cisco Systems, Inc. All rights reserved.</span></div>
<div class="line"><span class="comment"> * See COPYING in top-level directory.</span></div>
<div class="line"><span class="comment"> *</span></div>
<div class="line"><span class="comment"> * hwloc-hello.c</span></div>
<div class="line"><span class="comment"> */</span></div>
<div class="line"> </div>
<div class="line"><span class="preprocessor">#include "hwloc.h"</span></div>
<div class="line"> </div>
<div class="line"><span class="preprocessor">#include <errno.h></span></div>
<div class="line"><span class="preprocessor">#include <stdio.h></span></div>
<div class="line"><span class="preprocessor">#include <string.h></span></div>
<div class="line"> </div>
<div class="line"><span class="keyword">static</span> <span class="keywordtype">void</span> print_children(<a class="code hl_typedef" href="a00166.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, <a class="code hl_struct" href="a00220.html">hwloc_obj_t</a> obj,</div>
<div class="line"> <span class="keywordtype">int</span> depth)</div>
<div class="line">{</div>
<div class="line"> <span class="keywordtype">char</span> type[32], attr[1024];</div>
<div class="line"> <span class="keywordtype">unsigned</span> i;</div>
<div class="line"> </div>
<div class="line"> <a class="code hl_function" href="a00168.html#gadb8765c260edea80c52cd06a76639ba4">hwloc_obj_type_snprintf</a>(type, <span class="keyword">sizeof</span>(type), obj, 0);</div>
<div class="line"> printf(<span class="stringliteral">"%*s%s"</span>, 2*depth, <span class="stringliteral">""</span>, type);</div>
<div class="line"> <span class="keywordflow">if</span> (obj-><a class="code hl_variable" href="a00220.html#a61a7a80a68eaccbaaa28269e678c81a9">os_index</a> != (<span class="keywordtype">unsigned</span>) -1)</div>
<div class="line"> printf(<span class="stringliteral">"#%u"</span>, obj-><a class="code hl_variable" href="a00220.html#a61a7a80a68eaccbaaa28269e678c81a9">os_index</a>);</div>
<div class="line"> <a class="code hl_function" href="a00168.html#ga870e876931c282a1c7aee2f031912ce3">hwloc_obj_attr_snprintf</a>(attr, <span class="keyword">sizeof</span>(attr), obj, <span class="stringliteral">" "</span>, 0);</div>
<div class="line"> <span class="keywordflow">if</span> (*attr)</div>
<div class="line"> printf(<span class="stringliteral">"(%s)"</span>, attr);</div>
<div class="line"> printf(<span class="stringliteral">"\n"</span>);</div>
<div class="line"> <span class="keywordflow">for</span> (i = 0; i < obj-><a class="code hl_variable" href="a00220.html#aac3f6da35c9b57599909a44ce2b716c1">arity</a>; i++) {</div>
<div class="line"> print_children(topology, obj-><a class="code hl_variable" href="a00220.html#a04d05403da37bfe17cd63b7c7dd07b1f">children</a>[i], depth + 1);</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">void</span>)</div>
<div class="line">{</div>
<div class="line"> <span class="keywordtype">int</span> depth;</div>
<div class="line"> <span class="keywordtype">unsigned</span> i, n;</div>
<div class="line"> <span class="keywordtype">unsigned</span> <span class="keywordtype">long</span> size;</div>
<div class="line"> <span class="keywordtype">int</span> levels;</div>
<div class="line"> <span class="keywordtype">char</span> <span class="keywordtype">string</span>[128];</div>
<div class="line"> <span class="keywordtype">int</span> topodepth;</div>
<div class="line"> <span class="keywordtype">void</span> *m;</div>
<div class="line"> <a class="code hl_typedef" href="a00166.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology;</div>
<div class="line"> <a class="code hl_typedef" href="a00163.html#ga4bbf39b68b6f568fb92739e7c0ea7801">hwloc_cpuset_t</a> cpuset;</div>
<div class="line"> <a class="code hl_struct" href="a00220.html">hwloc_obj_t</a> obj;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">/* Allocate and initialize topology object. */</span></div>
<div class="line"> <a class="code hl_function" href="a00166.html#ga03fd4a16d8b9ee1ffc32b25fd2f6bdfa">hwloc_topology_init</a>(&topology);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">/* ... Optionally, put detection configuration here to ignore</span></div>
<div class="line"><span class="comment"> some objects types, define a synthetic topology, etc....</span></div>
<div class="line"><span class="comment"></span> </div>
<div class="line"><span class="comment"> The default is to detect all the objects of the machine that</span></div>
<div class="line"><span class="comment"> the caller is allowed to access. See Configure Topology</span></div>
<div class="line"><span class="comment"> Detection. */</span></div>
<div class="line"> </div>
<div class="line"> <span class="comment">/* Perform the topology detection. */</span></div>
<div class="line"> <a class="code hl_function" href="a00166.html#gabdf58d87ad77f6615fccdfe0535ff826">hwloc_topology_load</a>(topology);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">/* Optionally, get some additional topology information</span></div>
<div class="line"><span class="comment"> in case we need the topology depth later. */</span></div>
<div class="line"> topodepth = <a class="code hl_function" href="a00167.html#gae54d1782ca9b54bea915f5c18a9158fa">hwloc_topology_get_depth</a>(topology);</div>
<div class="line"> </div>
<div class="line"><span class="comment"> /*****************************************************************</span></div>
<div class="line"><span class="comment"> * First example:</span></div>
<div class="line"><span class="comment"> * Walk the topology with an array style, from level 0 (always</span></div>
<div class="line"><span class="comment"> * the system level) to the lowest level (always the proc level).</span></div>
<div class="line"><span class="comment"> *****************************************************************/</span></div>
<div class="line"> <span class="keywordflow">for</span> (depth = 0; depth < topodepth; depth++) {</div>
<div class="line"> printf(<span class="stringliteral">"*** Objects at level %d\n"</span>, depth);</div>
<div class="line"> <span class="keywordflow">for</span> (i = 0; i < <a class="code hl_function" href="a00167.html#ga1d5ceafe8130fe6e8657bf0bc666ba50">hwloc_get_nbobjs_by_depth</a>(topology, depth);</div>
<div class="line"> i++) {</div>
<div class="line"> <a class="code hl_function" href="a00168.html#gadb8765c260edea80c52cd06a76639ba4">hwloc_obj_type_snprintf</a>(<span class="keywordtype">string</span>, <span class="keyword">sizeof</span>(<span class="keywordtype">string</span>),</div>
<div class="line"> <a class="code hl_function" href="a00167.html#ga391f6b2613f0065673eaa4069b93d4e0">hwloc_get_obj_by_depth</a>(topology, depth, i), 0);</div>
<div class="line"> printf(<span class="stringliteral">"Index %u: %s\n"</span>, i, <span class="keywordtype">string</span>);</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"><span class="comment"> /*****************************************************************</span></div>
<div class="line"><span class="comment"> * Second example:</span></div>
<div class="line"><span class="comment"> * Walk the topology with a tree style.</span></div>
<div class="line"><span class="comment"> *****************************************************************/</span></div>
<div class="line"> printf(<span class="stringliteral">"*** Printing overall tree\n"</span>);</div>
<div class="line"> print_children(topology, <a class="code hl_function" href="a00167.html#gae76ac1ab6b8898bfe7667408b84c61d0">hwloc_get_root_obj</a>(topology), 0);</div>
<div class="line"> </div>
<div class="line"><span class="comment"> /*****************************************************************</span></div>
<div class="line"><span class="comment"> * Third example:</span></div>
<div class="line"><span class="comment"> * Print the number of packages.</span></div>
<div class="line"><span class="comment"> *****************************************************************/</span></div>
<div class="line"> depth = <a class="code hl_function" href="a00167.html#ga8bec782e21be313750da70cf7428b374">hwloc_get_type_depth</a>(topology, <a class="code hl_enumvalue" href="a00164.html#ggacd37bb612667dc437d66bfb175a8dc55ab16ab8c0dbffc234921d86f3dfb63129">HWLOC_OBJ_PACKAGE</a>);</div>
<div class="line"> <span class="keywordflow">if</span> (depth == <a class="code hl_enumvalue" href="a00167.html#ggaf4e663cf42bbe20756b849c6293ef575a0565ab92ab72cb0cec91e23003294aad">HWLOC_TYPE_DEPTH_UNKNOWN</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"*** The number of packages is unknown\n"</span>);</div>
<div class="line"> } <span class="keywordflow">else</span> {</div>
<div class="line"> printf(<span class="stringliteral">"*** %u package(s)\n"</span>,</div>
<div class="line"> <a class="code hl_function" href="a00167.html#ga1d5ceafe8130fe6e8657bf0bc666ba50">hwloc_get_nbobjs_by_depth</a>(topology, depth));</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"><span class="comment"> /*****************************************************************</span></div>
<div class="line"><span class="comment"> * Fourth example:</span></div>
<div class="line"><span class="comment"> * Compute the amount of cache that the first logical processor</span></div>
<div class="line"><span class="comment"> * has above it.</span></div>
<div class="line"><span class="comment"> *****************************************************************/</span></div>
<div class="line"> levels = 0;</div>
<div class="line"> size = 0;</div>
<div class="line"> <span class="keywordflow">for</span> (obj = <a class="code hl_function" href="a00167.html#ga1005a33633ddf9f730de692133e83dbd">hwloc_get_obj_by_type</a>(topology, <a class="code hl_enumvalue" href="a00164.html#ggacd37bb612667dc437d66bfb175a8dc55abca6887e80cb291353b0a0c1da83f661">HWLOC_OBJ_PU</a>, 0);</div>
<div class="line"> obj;</div>
<div class="line"> obj = obj-><a class="code hl_variable" href="a00220.html#adc494f6aed939992be1c55cca5822900">parent</a>)</div>
<div class="line"> <span class="keywordflow">if</span> (<a class="code hl_function" href="a00175.html#ga2ed589bea28711e80b92066510a5607d">hwloc_obj_type_is_cache</a>(obj-><a class="code hl_variable" href="a00220.html#acc4f0803f244867e68fe0036800be5de">type</a>)) {</div>
<div class="line"> levels++;</div>
<div class="line"> size += obj-><a class="code hl_variable" href="a00220.html#accd40e29f71f19e88db62ea3df02adc8">attr</a>-><a class="code hl_variable" href="a00224.html#a23f553f3252c9d13f2338231cd354ea9">cache</a>.<a class="code hl_variable" href="a00236.html#abe5e788943ed04302976740c829674c0">size</a>;</div>
<div class="line"> }</div>
<div class="line"> printf(<span class="stringliteral">"*** Logical processor 0 has %d caches totaling %luKB\n"</span>,</div>
<div class="line"> levels, size / 1024);</div>
<div class="line"> </div>
<div class="line"><span class="comment"> /*****************************************************************</span></div>
<div class="line"><span class="comment"> * Fifth example:</span></div>
<div class="line"><span class="comment"> * Bind to only one thread of the last core of the machine.</span></div>
<div class="line"><span class="comment"> *</span></div>
<div class="line"><span class="comment"> * First find out where cores are, or else smaller sets of CPUs if</span></div>
<div class="line"><span class="comment"> * the OS doesn't have the notion of a "core".</span></div>
<div class="line"><span class="comment"> *****************************************************************/</span></div>
<div class="line"> depth = <a class="code hl_function" href="a00167.html#gae395d32536ecc0fc916737b655d9d7a1">hwloc_get_type_or_below_depth</a>(topology, <a class="code hl_enumvalue" href="a00164.html#ggacd37bb612667dc437d66bfb175a8dc55ac793958f330bca371aa1535de8aff45f">HWLOC_OBJ_CORE</a>);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">/* Get last core. */</span></div>
<div class="line"> obj = <a class="code hl_function" href="a00167.html#ga391f6b2613f0065673eaa4069b93d4e0">hwloc_get_obj_by_depth</a>(topology, depth,</div>
<div class="line"> <a class="code hl_function" href="a00167.html#ga1d5ceafe8130fe6e8657bf0bc666ba50">hwloc_get_nbobjs_by_depth</a>(topology, depth) - 1);</div>
<div class="line"> <span class="keywordflow">if</span> (obj) {</div>
<div class="line"> <span class="comment">/* Get a copy of its cpuset that we may modify. */</span></div>
<div class="line"> cpuset = <a class="code hl_function" href="a00185.html#gae679434c1a5f41d3560a8a7e2c1b0dee">hwloc_bitmap_dup</a>(obj-><a class="code hl_variable" href="a00220.html#a67925e0f2c47f50408fbdb9bddd0790f">cpuset</a>);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">/* Get only one logical processor (in case the core is</span></div>
<div class="line"><span class="comment"> SMT/hyper-threaded). */</span></div>
<div class="line"> <a class="code hl_function" href="a00185.html#gaa611a77c092e679246afdf9a60d5db8b">hwloc_bitmap_singlify</a>(cpuset);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">/* And try to bind ourself there. */</span></div>
<div class="line"> <span class="keywordflow">if</span> (<a class="code hl_function" href="a00170.html#ga80bc07473a8edf840cae17bd7ec21d48">hwloc_set_cpubind</a>(topology, cpuset, 0)) {</div>
<div class="line"> <span class="keywordtype">char</span> *str;</div>
<div class="line"> <span class="keywordtype">int</span> error = errno;</div>
<div class="line"> <a class="code hl_function" href="a00185.html#ga0fece972134fdecf2da9bc7a11dd827e">hwloc_bitmap_asprintf</a>(&str, obj-><a class="code hl_variable" href="a00220.html#a67925e0f2c47f50408fbdb9bddd0790f">cpuset</a>);</div>
<div class="line"> printf(<span class="stringliteral">"Couldn't bind to cpuset %s: %s\n"</span>, str, strerror(error));</div>
<div class="line"> free(str);</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"> <span class="comment">/* Free our cpuset copy */</span></div>
<div class="line"> <a class="code hl_function" href="a00185.html#ga156130d85b3a0674d6e0e6770fe68fbe">hwloc_bitmap_free</a>(cpuset);</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"><span class="comment"> /*****************************************************************</span></div>
<div class="line"><span class="comment"> * Sixth example:</span></div>
<div class="line"><span class="comment"> * Allocate some memory on the last NUMA node, bind some existing</span></div>
<div class="line"><span class="comment"> * memory to the last NUMA node.</span></div>
<div class="line"><span class="comment"> *****************************************************************/</span></div>
<div class="line"> <span class="comment">/* Get last node. There's always at least one. */</span></div>
<div class="line"> n = <a class="code hl_function" href="a00167.html#ga53caf2bdef1125a2ac4bd792227f86c5">hwloc_get_nbobjs_by_type</a>(topology, <a class="code hl_enumvalue" href="a00164.html#ggacd37bb612667dc437d66bfb175a8dc55a9d917a3e5497950c6d8948b8e183db5a">HWLOC_OBJ_NUMANODE</a>);</div>
<div class="line"> obj = <a class="code hl_function" href="a00167.html#ga1005a33633ddf9f730de692133e83dbd">hwloc_get_obj_by_type</a>(topology, <a class="code hl_enumvalue" href="a00164.html#ggacd37bb612667dc437d66bfb175a8dc55a9d917a3e5497950c6d8948b8e183db5a">HWLOC_OBJ_NUMANODE</a>, n - 1);</div>
<div class="line"> </div>
<div class="line"> size = 1024*1024;</div>
<div class="line"> m = <a class="code hl_function" href="a00171.html#gadf87089ef533db40460ccc24b5bc0d65">hwloc_alloc_membind</a>(topology, size, obj-><a class="code hl_variable" href="a00220.html#a08f0d0e16c619a6e653526cbee4ffea3">nodeset</a>,</div>
<div class="line"> <a class="code hl_enumvalue" href="a00171.html#ggac9764f79505775d06407b40f5e4661e8ad811fa4b2a6002c4d63695a408ffde2c">HWLOC_MEMBIND_BIND</a>, <a class="code hl_enumvalue" href="a00171.html#ggab00475fd98815bf4fb9aaf752030e7d2a71f19fe4505f1c083dc8e6f7bdea6256">HWLOC_MEMBIND_BYNODESET</a>);</div>
<div class="line"> <a class="code hl_function" href="a00171.html#ga32dbd4f54e9e4a7179f2dde37ffe6ad7">hwloc_free</a>(topology, m, size);</div>
<div class="line"> </div>
<div class="line"> m = malloc(size);</div>
<div class="line"> <a class="code hl_function" href="a00171.html#gaf881faefe20701229f07dd7dbd0125ed">hwloc_set_area_membind</a>(topology, m, size, obj-><a class="code hl_variable" href="a00220.html#a08f0d0e16c619a6e653526cbee4ffea3">nodeset</a>,</div>
<div class="line"> <a class="code hl_enumvalue" href="a00171.html#ggac9764f79505775d06407b40f5e4661e8ad811fa4b2a6002c4d63695a408ffde2c">HWLOC_MEMBIND_BIND</a>, <a class="code hl_enumvalue" href="a00171.html#ggab00475fd98815bf4fb9aaf752030e7d2a71f19fe4505f1c083dc8e6f7bdea6256">HWLOC_MEMBIND_BYNODESET</a>);</div>
<div class="line"> free(m);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">/* Destroy topology object. */</span></div>
<div class="line"> <a class="code hl_function" href="a00166.html#ga9f34a640b6fd28d23699d4d084667b15">hwloc_topology_destroy</a>(topology);</div>
<div class="line"> </div>
<div class="line"> <span class="keywordflow">return</span> 0;</div>
<div class="line">}</div>
<div class="ttc" id="aa00163_html_ga4bbf39b68b6f568fb92739e7c0ea7801"><div class="ttname"><a href="a00163.html#ga4bbf39b68b6f568fb92739e7c0ea7801">hwloc_cpuset_t</a></div><div class="ttdeci">hwloc_bitmap_t hwloc_cpuset_t</div><div class="ttdoc">A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.</div><div class="ttdef"><b>Definition</b> hwloc.h:161</div></div>
<div class="ttc" id="aa00164_html_ggacd37bb612667dc437d66bfb175a8dc55a9d917a3e5497950c6d8948b8e183db5a"><div class="ttname"><a href="a00164.html#ggacd37bb612667dc437d66bfb175a8dc55a9d917a3e5497950c6d8948b8e183db5a">HWLOC_OBJ_NUMANODE</a></div><div class="ttdeci">@ HWLOC_OBJ_NUMANODE</div><div class="ttdoc">NUMA node. An object that contains memory that is directly and byte-accessible to the host processors...</div><div class="ttdef"><b>Definition</b> hwloc.h:257</div></div>
<div class="ttc" id="aa00164_html_ggacd37bb612667dc437d66bfb175a8dc55ab16ab8c0dbffc234921d86f3dfb63129"><div class="ttname"><a href="a00164.html#ggacd37bb612667dc437d66bfb175a8dc55ab16ab8c0dbffc234921d86f3dfb63129">HWLOC_OBJ_PACKAGE</a></div><div class="ttdeci">@ HWLOC_OBJ_PACKAGE</div><div class="ttdoc">Physical package. The physical package that usually gets inserted into a socket on the motherboard....</div><div class="ttdef"><b>Definition</b> hwloc.h:212</div></div>
<div class="ttc" id="aa00164_html_ggacd37bb612667dc437d66bfb175a8dc55abca6887e80cb291353b0a0c1da83f661"><div class="ttname"><a href="a00164.html#ggacd37bb612667dc437d66bfb175a8dc55abca6887e80cb291353b0a0c1da83f661">HWLOC_OBJ_PU</a></div><div class="ttdeci">@ HWLOC_OBJ_PU</div><div class="ttdoc">Processing Unit, or (Logical) Processor. An execution unit (may share a core with some other logical ...</div><div class="ttdef"><b>Definition</b> hwloc.h:222</div></div>
<div class="ttc" id="aa00164_html_ggacd37bb612667dc437d66bfb175a8dc55ac793958f330bca371aa1535de8aff45f"><div class="ttname"><a href="a00164.html#ggacd37bb612667dc437d66bfb175a8dc55ac793958f330bca371aa1535de8aff45f">HWLOC_OBJ_CORE</a></div><div class="ttdeci">@ HWLOC_OBJ_CORE</div><div class="ttdoc">Core. A computation unit (may be shared by several PUs, aka logical processors).</div><div class="ttdef"><b>Definition</b> hwloc.h:218</div></div>
<div class="ttc" id="aa00166_html_ga03fd4a16d8b9ee1ffc32b25fd2f6bdfa"><div class="ttname"><a href="a00166.html#ga03fd4a16d8b9ee1ffc32b25fd2f6bdfa">hwloc_topology_init</a></div><div class="ttdeci">int hwloc_topology_init(hwloc_topology_t *topologyp)</div><div class="ttdoc">Allocate a topology context.</div></div>
<div class="ttc" id="aa00166_html_ga9d1e76ee15a7dee158b786c30b6a6e38"><div class="ttname"><a href="a00166.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></div><div class="ttdeci">struct hwloc_topology * hwloc_topology_t</div><div class="ttdoc">Topology context.</div><div class="ttdef"><b>Definition</b> hwloc.h:743</div></div>
<div class="ttc" id="aa00166_html_ga9f34a640b6fd28d23699d4d084667b15"><div class="ttname"><a href="a00166.html#ga9f34a640b6fd28d23699d4d084667b15">hwloc_topology_destroy</a></div><div class="ttdeci">void hwloc_topology_destroy(hwloc_topology_t topology)</div><div class="ttdoc">Terminate and free a topology context.</div></div>
<div class="ttc" id="aa00166_html_gabdf58d87ad77f6615fccdfe0535ff826"><div class="ttname"><a href="a00166.html#gabdf58d87ad77f6615fccdfe0535ff826">hwloc_topology_load</a></div><div class="ttdeci">int hwloc_topology_load(hwloc_topology_t topology)</div><div class="ttdoc">Build the actual topology.</div></div>
<div class="ttc" id="aa00167_html_ga1005a33633ddf9f730de692133e83dbd"><div class="ttname"><a href="a00167.html#ga1005a33633ddf9f730de692133e83dbd">hwloc_get_obj_by_type</a></div><div class="ttdeci">hwloc_obj_t hwloc_get_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)</div><div class="ttdoc">Returns the topology object at logical index idx with type type.</div></div>
<div class="ttc" id="aa00167_html_ga1d5ceafe8130fe6e8657bf0bc666ba50"><div class="ttname"><a href="a00167.html#ga1d5ceafe8130fe6e8657bf0bc666ba50">hwloc_get_nbobjs_by_depth</a></div><div class="ttdeci">unsigned hwloc_get_nbobjs_by_depth(hwloc_topology_t topology, int depth)</div><div class="ttdoc">Returns the width of level at depth depth.</div></div>
<div class="ttc" id="aa00167_html_ga391f6b2613f0065673eaa4069b93d4e0"><div class="ttname"><a href="a00167.html#ga391f6b2613f0065673eaa4069b93d4e0">hwloc_get_obj_by_depth</a></div><div class="ttdeci">hwloc_obj_t hwloc_get_obj_by_depth(hwloc_topology_t topology, int depth, unsigned idx)</div><div class="ttdoc">Returns the topology object at logical index idx from depth depth.</div></div>
<div class="ttc" id="aa00167_html_ga53caf2bdef1125a2ac4bd792227f86c5"><div class="ttname"><a href="a00167.html#ga53caf2bdef1125a2ac4bd792227f86c5">hwloc_get_nbobjs_by_type</a></div><div class="ttdeci">int hwloc_get_nbobjs_by_type(hwloc_topology_t topology, hwloc_obj_type_t type)</div><div class="ttdoc">Returns the width of level type type.</div></div>
<div class="ttc" id="aa00167_html_ga8bec782e21be313750da70cf7428b374"><div class="ttname"><a href="a00167.html#ga8bec782e21be313750da70cf7428b374">hwloc_get_type_depth</a></div><div class="ttdeci">int hwloc_get_type_depth(hwloc_topology_t topology, hwloc_obj_type_t type)</div><div class="ttdoc">Returns the depth of objects of type type.</div></div>
<div class="ttc" id="aa00167_html_gae395d32536ecc0fc916737b655d9d7a1"><div class="ttname"><a href="a00167.html#gae395d32536ecc0fc916737b655d9d7a1">hwloc_get_type_or_below_depth</a></div><div class="ttdeci">int hwloc_get_type_or_below_depth(hwloc_topology_t topology, hwloc_obj_type_t type)</div><div class="ttdoc">Returns the depth of objects of type type or below.</div></div>
<div class="ttc" id="aa00167_html_gae54d1782ca9b54bea915f5c18a9158fa"><div class="ttname"><a href="a00167.html#gae54d1782ca9b54bea915f5c18a9158fa">hwloc_topology_get_depth</a></div><div class="ttdeci">int hwloc_topology_get_depth(hwloc_topology_t restrict topology)</div><div class="ttdoc">Get the depth of the hierarchical tree of objects.</div></div>
<div class="ttc" id="aa00167_html_gae76ac1ab6b8898bfe7667408b84c61d0"><div class="ttname"><a href="a00167.html#gae76ac1ab6b8898bfe7667408b84c61d0">hwloc_get_root_obj</a></div><div class="ttdeci">hwloc_obj_t hwloc_get_root_obj(hwloc_topology_t topology)</div><div class="ttdoc">Returns the top-object of the topology-tree.</div></div>
<div class="ttc" id="aa00167_html_ggaf4e663cf42bbe20756b849c6293ef575a0565ab92ab72cb0cec91e23003294aad"><div class="ttname"><a href="a00167.html#ggaf4e663cf42bbe20756b849c6293ef575a0565ab92ab72cb0cec91e23003294aad">HWLOC_TYPE_DEPTH_UNKNOWN</a></div><div class="ttdeci">@ HWLOC_TYPE_DEPTH_UNKNOWN</div><div class="ttdoc">No object of given type exists in the topology.</div><div class="ttdef"><b>Definition</b> hwloc.h:880</div></div>
<div class="ttc" id="aa00168_html_ga870e876931c282a1c7aee2f031912ce3"><div class="ttname"><a href="a00168.html#ga870e876931c282a1c7aee2f031912ce3">hwloc_obj_attr_snprintf</a></div><div class="ttdeci">int hwloc_obj_attr_snprintf(char *restrict string, size_t size, hwloc_obj_t obj, const char *restrict separator, int verbose)</div><div class="ttdoc">Stringify the attributes of a given topology object into a human-readable form.</div></div>
<div class="ttc" id="aa00168_html_gadb8765c260edea80c52cd06a76639ba4"><div class="ttname"><a href="a00168.html#gadb8765c260edea80c52cd06a76639ba4">hwloc_obj_type_snprintf</a></div><div class="ttdeci">int hwloc_obj_type_snprintf(char *restrict string, size_t size, hwloc_obj_t obj, int verbose)</div><div class="ttdoc">Stringify the type of a given topology object into a human-readable form.</div></div>
<div class="ttc" id="aa00170_html_ga80bc07473a8edf840cae17bd7ec21d48"><div class="ttname"><a href="a00170.html#ga80bc07473a8edf840cae17bd7ec21d48">hwloc_set_cpubind</a></div><div class="ttdeci">int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)</div><div class="ttdoc">Bind current process or thread on CPUs given in physical bitmap set.</div></div>
<div class="ttc" id="aa00171_html_ga32dbd4f54e9e4a7179f2dde37ffe6ad7"><div class="ttname"><a href="a00171.html#ga32dbd4f54e9e4a7179f2dde37ffe6ad7">hwloc_free</a></div><div class="ttdeci">int hwloc_free(hwloc_topology_t topology, void *addr, size_t len)</div><div class="ttdoc">Free memory that was previously allocated by hwloc_alloc() or hwloc_alloc_membind().</div></div>
<div class="ttc" id="aa00171_html_gadf87089ef533db40460ccc24b5bc0d65"><div class="ttname"><a href="a00171.html#gadf87089ef533db40460ccc24b5bc0d65">hwloc_alloc_membind</a></div><div class="ttdeci">void * hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)</div><div class="ttdoc">Allocate some memory on NUMA memory nodes specified by set.</div></div>
<div class="ttc" id="aa00171_html_gaf881faefe20701229f07dd7dbd0125ed"><div class="ttname"><a href="a00171.html#gaf881faefe20701229f07dd7dbd0125ed">hwloc_set_area_membind</a></div><div class="ttdeci">int hwloc_set_area_membind(hwloc_topology_t topology, const void *addr, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)</div><div class="ttdoc">Bind the already-allocated memory identified by (addr, len) to the NUMA node(s) specified by set.</div></div>
<div class="ttc" id="aa00171_html_ggab00475fd98815bf4fb9aaf752030e7d2a71f19fe4505f1c083dc8e6f7bdea6256"><div class="ttname"><a href="a00171.html#ggab00475fd98815bf4fb9aaf752030e7d2a71f19fe4505f1c083dc8e6f7bdea6256">HWLOC_MEMBIND_BYNODESET</a></div><div class="ttdeci">@ HWLOC_MEMBIND_BYNODESET</div><div class="ttdoc">Consider the bitmap argument as a nodeset.</div><div class="ttdef"><b>Definition</b> hwloc.h:1635</div></div>
<div class="ttc" id="aa00171_html_ggac9764f79505775d06407b40f5e4661e8ad811fa4b2a6002c4d63695a408ffde2c"><div class="ttname"><a href="a00171.html#ggac9764f79505775d06407b40f5e4661e8ad811fa4b2a6002c4d63695a408ffde2c">HWLOC_MEMBIND_BIND</a></div><div class="ttdeci">@ HWLOC_MEMBIND_BIND</div><div class="ttdoc">Allocate memory on the specified nodes.</div><div class="ttdef"><b>Definition</b> hwloc.h:1537</div></div>
<div class="ttc" id="aa00175_html_ga2ed589bea28711e80b92066510a5607d"><div class="ttname"><a href="a00175.html#ga2ed589bea28711e80b92066510a5607d">hwloc_obj_type_is_cache</a></div><div class="ttdeci">int hwloc_obj_type_is_cache(hwloc_obj_type_t type)</div><div class="ttdoc">Check whether an object type is a CPU Cache (Data, Unified or Instruction).</div></div>
<div class="ttc" id="aa00185_html_ga0fece972134fdecf2da9bc7a11dd827e"><div class="ttname"><a href="a00185.html#ga0fece972134fdecf2da9bc7a11dd827e">hwloc_bitmap_asprintf</a></div><div class="ttdeci">int hwloc_bitmap_asprintf(char **strp, hwloc_const_bitmap_t bitmap)</div><div class="ttdoc">Stringify a bitmap into a newly allocated string in the default hwloc format.</div></div>
<div class="ttc" id="aa00185_html_ga156130d85b3a0674d6e0e6770fe68fbe"><div class="ttname"><a href="a00185.html#ga156130d85b3a0674d6e0e6770fe68fbe">hwloc_bitmap_free</a></div><div class="ttdeci">void hwloc_bitmap_free(hwloc_bitmap_t bitmap)</div><div class="ttdoc">Free bitmap bitmap.</div></div>
<div class="ttc" id="aa00185_html_gaa611a77c092e679246afdf9a60d5db8b"><div class="ttname"><a href="a00185.html#gaa611a77c092e679246afdf9a60d5db8b">hwloc_bitmap_singlify</a></div><div class="ttdeci">int hwloc_bitmap_singlify(hwloc_bitmap_t bitmap)</div><div class="ttdoc">Keep a single index among those set in bitmap bitmap.</div></div>
<div class="ttc" id="aa00185_html_gae679434c1a5f41d3560a8a7e2c1b0dee"><div class="ttname"><a href="a00185.html#gae679434c1a5f41d3560a8a7e2c1b0dee">hwloc_bitmap_dup</a></div><div class="ttdeci">hwloc_bitmap_t hwloc_bitmap_dup(hwloc_const_bitmap_t bitmap)</div><div class="ttdoc">Duplicate bitmap bitmap by allocating a new bitmap and copying bitmap contents.</div></div>
<div class="ttc" id="aa00220_html"><div class="ttname"><a href="a00220.html">hwloc_obj</a></div><div class="ttdoc">Structure of a topology object.</div><div class="ttdef"><b>Definition</b> hwloc.h:432</div></div>
<div class="ttc" id="aa00220_html_a04d05403da37bfe17cd63b7c7dd07b1f"><div class="ttname"><a href="a00220.html#a04d05403da37bfe17cd63b7c7dd07b1f">hwloc_obj::children</a></div><div class="ttdeci">struct hwloc_obj ** children</div><div class="ttdoc">Normal children, children[0 .. arity -1].</div><div class="ttdef"><b>Definition</b> hwloc.h:492</div></div>
<div class="ttc" id="aa00220_html_a08f0d0e16c619a6e653526cbee4ffea3"><div class="ttname"><a href="a00220.html#a08f0d0e16c619a6e653526cbee4ffea3">hwloc_obj::nodeset</a></div><div class="ttdeci">hwloc_nodeset_t nodeset</div><div class="ttdoc">NUMA nodes covered by this object or containing this object.</div><div class="ttdef"><b>Definition</b> hwloc.h:576</div></div>
<div class="ttc" id="aa00220_html_a61a7a80a68eaccbaaa28269e678c81a9"><div class="ttname"><a href="a00220.html#a61a7a80a68eaccbaaa28269e678c81a9">hwloc_obj::os_index</a></div><div class="ttdeci">unsigned os_index</div><div class="ttdoc">OS-provided physical index number. It is not guaranteed unique across the entire machine,...</div><div class="ttdef"><b>Definition</b> hwloc.h:437</div></div>
<div class="ttc" id="aa00220_html_a67925e0f2c47f50408fbdb9bddd0790f"><div class="ttname"><a href="a00220.html#a67925e0f2c47f50408fbdb9bddd0790f">hwloc_obj::cpuset</a></div><div class="ttdeci">hwloc_cpuset_t cpuset</div><div class="ttdoc">CPUs covered by this object.</div><div class="ttdef"><b>Definition</b> hwloc.h:548</div></div>
<div class="ttc" id="aa00220_html_aac3f6da35c9b57599909a44ce2b716c1"><div class="ttname"><a href="a00220.html#aac3f6da35c9b57599909a44ce2b716c1">hwloc_obj::arity</a></div><div class="ttdeci">unsigned arity</div><div class="ttdoc">Number of normal children. Memory, Misc and I/O children are not listed here but rather in their dedi...</div><div class="ttdef"><b>Definition</b> hwloc.h:488</div></div>
<div class="ttc" id="aa00220_html_acc4f0803f244867e68fe0036800be5de"><div class="ttname"><a href="a00220.html#acc4f0803f244867e68fe0036800be5de">hwloc_obj::type</a></div><div class="ttdeci">hwloc_obj_type_t type</div><div class="ttdoc">Type of object.</div><div class="ttdef"><b>Definition</b> hwloc.h:434</div></div>
<div class="ttc" id="aa00220_html_accd40e29f71f19e88db62ea3df02adc8"><div class="ttname"><a href="a00220.html#accd40e29f71f19e88db62ea3df02adc8">hwloc_obj::attr</a></div><div class="ttdeci">union hwloc_obj_attr_u * attr</div><div class="ttdoc">Object type-specific Attributes, may be NULL if no attribute value was found.</div><div class="ttdef"><b>Definition</b> hwloc.h:451</div></div>
<div class="ttc" id="aa00220_html_adc494f6aed939992be1c55cca5822900"><div class="ttname"><a href="a00220.html#adc494f6aed939992be1c55cca5822900">hwloc_obj::parent</a></div><div class="ttdeci">struct hwloc_obj * parent</div><div class="ttdoc">Parent, NULL if root (Machine object)</div><div class="ttdef"><b>Definition</b> hwloc.h:482</div></div>
<div class="ttc" id="aa00224_html_a23f553f3252c9d13f2338231cd354ea9"><div class="ttname"><a href="a00224.html#a23f553f3252c9d13f2338231cd354ea9">hwloc_obj_attr_u::cache</a></div><div class="ttdeci">struct hwloc_obj_attr_u::hwloc_cache_attr_s cache</div></div>
<div class="ttc" id="aa00236_html_abe5e788943ed04302976740c829674c0"><div class="ttname"><a href="a00236.html#abe5e788943ed04302976740c829674c0">hwloc_obj_attr_u::hwloc_cache_attr_s::size</a></div><div class="ttdeci">hwloc_uint64_t size</div><div class="ttdoc">Size of cache in bytes.</div><div class="ttdef"><b>Definition</b> hwloc.h:653</div></div>
</div><!-- fragment --><p>hwloc provides a <code>pkg-config</code> executable to obtain relevant compiler and linker flags. See <a class="el" href="a00366.html">Compiling software on top of hwloc's C API</a> for details on building program on top of hwloc's API using GNU Make or CMake.</p>
<p>On a machine 2 processor packages – each package of which has two processing cores – the output from running <code>hwloc-hello</code> could be something like the following:</p>
<pre class="fragment">shell$ ./hwloc-hello
*** Objects at level 0
Index 0: Machine
*** Objects at level 1
Index 0: Package#0
Index 1: Package#1
*** Objects at level 2
Index 0: Core#0
Index 1: Core#1
Index 2: Core#3
Index 3: Core#2
*** Objects at level 3
Index 0: PU#0
Index 1: PU#1
Index 2: PU#2
Index 3: PU#3
*** Printing overall tree
Machine
Package#0
Core#0
PU#0
Core#1
PU#1
Package#1
Core#3
PU#2
Core#2
PU#3
*** 2 package(s)
*** Logical processor 0 has 0 caches totaling 0KB
shell$
</pre><h1><a class="anchor" id="bugs"></a>
Questions and Bugs</h1>
<p>Bugs should be reported in the tracker (<a href="https://github.com/open-mpi/hwloc/issues">https://github.com/open-mpi/hwloc/issues</a>). Opening a new issue automatically displays lots of hints about how to debug and report issues.</p>
<p>Questions may be sent to the users or developers mailing lists (<a href="https://www.open-mpi.org/community/lists/hwloc.php">https://www.open-mpi.org/community/lists/hwloc.php</a>).</p>
<p>There is also a <code>#hwloc</code> IRC channel on Libera Chat (<code>irc.libera.chat</code>).</p>
<h1><a class="anchor" id="history"></a>
History / Credits</h1>
<p>hwloc is the evolution and merger of the libtopology project and the Portable Linux Processor Affinity (PLPA) (<a href="https://www.open-mpi.org/projects/plpa/">https://www.open-mpi.org/projects/plpa/</a>) project. Because of functional and ideological overlap, these two code bases and ideas were merged and released under the name "hwloc" as an Open MPI sub-project.</p>
<p>libtopology was initially developed by the Inria Runtime Team-Project. PLPA was initially developed by the Open MPI development team as a sub-project. Both are now deprecated in favor of hwloc, which is distributed as an Open MPI sub-project. </p>
</div></div><!-- PageDoc -->
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.8
</small></address>
</body>
</html>
|
