← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/hwloc/oneiric

« back to all changes in this revision

Viewing changes to doc/doxygen-doc/html/index.html-e

  • Committer: Bazaar Package Importer
  • Author(s): Samuel Thibault
  • Date: 2009-11-24 20:42:08 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20091124204208-kwnjo65ylozs2big
Tags: 0.9.3~rc1-1
* New upstream bugfix release.
* patches/binutils-gold.patch: Merged upstream.
* patches/hwloc-hello.patch: Merged upstream.
* control: Add Build-Depends-Indep: doxygen, texlive-latex-base, transfig to
  regenerate the documentation.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/doxygen-doc/html/index.html-e
12
12
  <div class="tabs">
13
13
    <ul>
14
14
      <li class="current"><a href="index.html"><span>Main&nbsp;Page</span></a></li>
15
 
      <li><a href="pages.html"><span>Related&nbsp;Pages</span></a></li>
16
15
      <li><a href="modules.html"><span>Modules</span></a></li>
17
16
      <li><a href="annotated.html"><span>Data&nbsp;Structures</span></a></li>
18
17
      <li><a href="files.html"><span>Files</span></a></li>
20
19
  </div>
21
20
</div>
22
21
<div class="contents">
23
 
<h1>hwloc</h1><h3>0.9.2 </h3><h1 class="sub">Portable abstraction of hierarchical architectures for high-performance computing</h1>
 
22
<h1>hwloc</h1><h3>0.9.3rc1 </h3><h1 class="sub">Portable abstraction of hierarchical architectures for high-performance computing</h1>
24
23
<hr/>
25
24
 
26
25
<div class="section" id="introduction">
79
78
<div align="center">
80
79
<img src="dudley.png" alt="dudley.png"/>
81
80
</div>
82
 
 <div class="fragment"><pre class="fragment">System(15GB)
83
 
  Socket<span class="preprocessor">#0 + L3(4096KB)</span>
84
 
<span class="preprocessor"></span>    L2(1024KB) + L1(16KB) + Core#0
 
81
 <div class="fragment"><pre class="fragment">
 
82
System(15GB)
 
83
  Socket#0 + L3(4096KB)
 
84
    L2(1024KB) + L1(16KB) + Core#0
85
85
      P#0
86
86
      P#8
87
87
    L2(1024KB) + L1(16KB) + Core#1
88
88
      P#4
89
89
      P#12
90
90
  Socket#1 + L3(4096KB)
91
 
    L2(1024KB) + L1(16KB) + Core<span class="preprocessor">#0</span>
92
 
<span class="preprocessor"></span>      P#1
 
91
    L2(1024KB) + L1(16KB) + Core#0
 
92
      P#1
93
93
      P#9
94
94
    L2(1024KB) + L1(16KB) + Core#1
95
95
      P#5
96
96
      P#13
97
97
  Socket#2 + L3(4096KB)
98
 
    L2(1024KB) + L1(16KB) + Core<span class="preprocessor">#0</span>
99
 
<span class="preprocessor"></span>      P#2
 
98
    L2(1024KB) + L1(16KB) + Core#0
 
99
      P#2
100
100
      P#10
101
101
    L2(1024KB) + L1(16KB) + Core#1
102
102
      P#6
103
103
      P#14
104
104
  Socket#3 + L3(4096KB)
105
 
    L2(1024KB) + L1(16KB) + Core<span class="preprocessor">#0</span>
106
 
<span class="preprocessor"></span>      P#3
 
105
    L2(1024KB) + L1(16KB) + Core#0
 
106
      P#3
107
107
      P#11
108
108
    L2(1024KB) + L1(16KB) + Core#1
109
109
      P#7
112
112
<div align="center">
113
113
<img src="hagrid.png" alt="hagrid.png"/>
114
114
</div>
115
 
 <div class="fragment"><pre class="fragment">System(62GB)
116
 
  Node<span class="preprocessor">#0(8190MB) + Socket#0</span>
117
 
<span class="preprocessor"></span>    L2(1024KB) + L1(64KB) + Core#0 + P#0
 
115
 <div class="fragment"><pre class="fragment">
 
116
System(62GB)
 
117
  Node#0(8190MB) + Socket#0
 
118
    L2(1024KB) + L1(64KB) + Core#0 + P#0
118
119
    L2(1024KB) + L1(64KB) + Core#1 + P#1
119
120
  Node#1(8192MB) + Socket#1
120
121
    L2(1024KB) + L1(64KB) + Core#0 + P#2
141
142
<div align="center">
142
143
<img src="emmett.png" alt="emmett.png"/>
143
144
</div>
144
 
 <div class="fragment"><pre class="fragment">System(15GB)
145
 
  Socket<span class="preprocessor">#0</span>
146
 
<span class="preprocessor"></span>    L2(4096KB)
147
 
      L1(32KB) + Core<span class="preprocessor">#0 + P#0</span>
148
 
<span class="preprocessor"></span>      L1(32KB) + Core#1 + P#4
149
 
    L2(4096KB)
150
 
      L1(32KB) + Core<span class="preprocessor">#2 + P#2</span>
151
 
<span class="preprocessor"></span>      L1(32KB) + Core#3 + P#6
 
145
 <div class="fragment"><pre class="fragment">
 
146
System(15GB)
 
147
  Socket#0
 
148
    L2(4096KB)
 
149
      L1(32KB) + Core#0 + P#0
 
150
      L1(32KB) + Core#1 + P#4
 
151
    L2(4096KB)
 
152
      L1(32KB) + Core#2 + P#2
 
153
      L1(32KB) + Core#3 + P#6
152
154
  Socket#1
153
155
    L2(4096KB)
154
 
      L1(32KB) + Core<span class="preprocessor">#0 + P#1</span>
155
 
<span class="preprocessor"></span>      L1(32KB) + Core#1 + P#5
 
156
      L1(32KB) + Core#0 + P#1
 
157
      L1(32KB) + Core#1 + P#5
156
158
    L2(4096KB)
157
 
      L1(32KB) + Core<span class="preprocessor">#2 + P#3</span>
158
 
<span class="preprocessor">      L1(32KB) + Core#3 + P#7</span>
 
159
      L1(32KB) + Core#2 + P#3
 
160
      L1(32KB) + Core#3 + P#7
159
161
</pre></div> 
160
162
</div><div class="section" id="interface">
161
163
<h2><a class="anchor" id="interface">
163
165
<p>The basic interface is available in <a class="el" href="hwloc_8h_source.html" title="The hwloc API.">hwloc.h</a>. It mostly offers low-level routines for advanced programmers that want to manually manipulate objects and follow links between them. Developers should look at <a class="el" href="helper_8h_source.html" title="High-level hwloc traversal helpers.">hwloc/helper.h</a>, which provides good higher-level topology traversal examples.</p>
164
166
<p>Each object contains a cpuset describing the list of processors that it contains. These cpusets may be used for <a class="el" href="group__hwlocality__binding.html">Binding</a>. hwloc offers an extensive cpuset manipulation interface in <a class="el" href="cpuset_8h_source.html" title="The Cpuset API, for use in hwloc itself.">hwloc/cpuset.h</a>.</p>
165
167
<p>Moreover, hwloc also comes with additional helpers for interoperability with several commonly used environments. For Linux, some specific helpers are available in <a class="el" href="linux_8h_source.html" title="Macros to help interaction between hwloc and Linux.">hwloc/linux.h</a>, and <a class="el" href="linux-libnuma_8h_source.html" title="Macros to help interaction between hwloc and Linux libnuma.">hwloc/linux-libnuma.h</a> if using libnuma. On glibc-based systems, additional helpers are available in <a class="el" href="glibc-sched_8h_source.html" title="Macros to help interaction between hwloc and glibc scheduling routines.">hwloc/glibc-sched.h</a>. For Linux systems with the OpenFabrics verbs library, some dedicated helpers are provided in <a class="el" href="openfabrics-verbs_8h_source.html" title="Macros to help interaction between hwloc and OpenFabrics verbs.">hwloc/openfabrics-verbs.h</a> (this helper file is not yet useful on non-Linux systems with the OpenFabrics verbs library).</p>
166
 
<p>To precisely define the vocabulary used by hwloc, a <a class="el" href="glossary.html">Glossary</a> is available and should probably be read first.</p>
 
168
<p>To precisely define the vocabulary used by hwloc, a <a class="el" href="index.html#glossary">Glossary</a> is available and should probably be read first.</p>
167
169
<p>Further 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/. If you are building from a Subversion checkout, 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
168
170
install" to $prefix/share/doc/hwloc/ and your systems default man page tree (under $prefix, of course).</p>
169
171
<p>The following section presents an example of API usage.</p>
170
172
<h2><a class="anchor" id="interface_example">
171
 
Interface example</a></h2>
172
 
<p>This section shows how to use hwloc with an small example <code>hwloc-hello.c</code> that just prints the topology and binds itself to the first processor of the second core of the machine.</p>
173
 
<p>Hardware Location provides a pkg-config object, so compiling the example boils down to</p>
174
 
<div class="fragment"><pre class="fragment">
175
 
CFLAGS += $(pkg-config --cflags hwloc)
176
 
LDLIBS += $(pkg-config --libs hwloc)
177
 
cc hwloc-hello.c $(CFLAGS) -o hwloc-hello $(LDLIBS)
178
 
</pre></div><div class="fragment"><pre class="fragment"><span class="comment">/* Example hwloc API program.</span>
 
173
API example</a></h2>
 
174
<p>The following small C example (named ``hwloc-hello.c'') prints the topology of the machine and bring the process to the first processor of the second core of the machine.</p>
 
175
<div class="fragment"><pre class="fragment"><span class="comment">/* Example hwloc API program.</span>
179
176
<span class="comment"> *</span>
180
177
<span class="comment"> * Copyright © 2009 INRIA, Université Bordeaux 1</span>
 
178
<span class="comment"> * Copyright © 2009 Cisco Systems, Inc.  All rights reserved.</span>
181
179
<span class="comment"> *</span>
182
 
<span class="comment"> * topo-hello.c </span>
 
180
<span class="comment"> * hwloc-hello.c </span>
183
181
<span class="comment"> */</span>
184
182
 
185
183
<span class="preprocessor">#include &lt;hwloc.h&gt;</span>
186
184
 
187
 
<span class="keyword">static</span> <span class="keywordtype">void</span> print_children(<a class="code" href="group__hwlocality__topology.html#ga9d1e76ee15a7dee158b786c30b6a6e38" title="Topology context.">hwloc_topology_t</a> topology, <a class="code" href="structhwloc__obj.html" title="Structure of a topology object.">hwloc_obj_t</a> obj, <span class="keywordtype">int</span> depth)
 
185
<span class="keyword">static</span> <span class="keywordtype">void</span> print_children(<a class="code" href="group__hwlocality__topology.html#ga9d1e76ee15a7dee158b786c30b6a6e38" title="Topology context.">hwloc_topology_t</a> topology, <a class="code" href="structhwloc__obj.html" title="Structure of a topology object.">hwloc_obj_t</a> obj, 
 
186
                           <span class="keywordtype">int</span> depth)
188
187
{
189
 
        <span class="keywordtype">char</span> <span class="keywordtype">string</span>[128];
190
 
        <span class="keywordtype">int</span> i;
 
188
    <span class="keywordtype">char</span> <span class="keywordtype">string</span>[128];
 
189
    <span class="keywordtype">int</span> i;
191
190
 
192
 
        <a class="code" href="group__hwlocality__conversion.html#ga612dc210053b65d2466ac7ad39db92a4" title="Stringify a given topology object into a human-readable form.">hwloc_obj_snprintf</a>(<span class="keywordtype">string</span>, <span class="keyword">sizeof</span>(<span class="keywordtype">string</span>), topology, obj, <span class="stringliteral">&quot;#&quot;</span>, 0);
193
 
        printf(<span class="stringliteral">&quot;%*s%s\n&quot;</span>, 2*depth, <span class="stringliteral">&quot;&quot;</span>, <span class="keywordtype">string</span>);
194
 
        <span class="keywordflow">for</span> (i = 0; i &lt; obj-&gt;<a class="code" href="structhwloc__obj.html#aac3f6da35c9b57599909a44ce2b716c1" title="Number of children.">arity</a>; i++)
195
 
                print_children(topology, obj-&gt;<a class="code" href="structhwloc__obj.html#a04d05403da37bfe17cd63b7c7dd07b1f" title="Children, children[0 .. arity -1].">children</a>[i], depth + 1);
 
191
    <a class="code" href="group__hwlocality__conversion.html#ga612dc210053b65d2466ac7ad39db92a4" title="Stringify a given topology object into a human-readable form.">hwloc_obj_snprintf</a>(<span class="keywordtype">string</span>, <span class="keyword">sizeof</span>(<span class="keywordtype">string</span>), topology, obj, <span class="stringliteral">&quot;#&quot;</span>, 0);
 
192
    printf(<span class="stringliteral">&quot;%*s%s\n&quot;</span>, 2*depth, <span class="stringliteral">&quot;&quot;</span>, <span class="keywordtype">string</span>);
 
193
    <span class="keywordflow">for</span> (i = 0; i &lt; obj-&gt;<a class="code" href="structhwloc__obj.html#aac3f6da35c9b57599909a44ce2b716c1" title="Number of children.">arity</a>; i++) {
 
194
        print_children(topology, obj-&gt;<a class="code" href="structhwloc__obj.html#a04d05403da37bfe17cd63b7c7dd07b1f" title="Children, children[0 .. arity -1].">children</a>[i], depth + 1);
 
195
    }
196
196
}
197
197
 
198
 
<span class="keywordtype">int</span> main(<span class="keywordtype">void</span>)
 
198
<span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span> **argv)
199
199
{
200
 
        <span class="comment">/* Topology object */</span>
201
 
        <a class="code" href="group__hwlocality__topology.html#ga9d1e76ee15a7dee158b786c30b6a6e38" title="Topology context.">hwloc_topology_t</a> topology;
202
 
 
203
 
        <span class="comment">/* Allocate and initialize topology object.  */</span>
204
 
        <a class="code" href="group__hwlocality__creation.html#ga03fd4a16d8b9ee1ffc32b25fd2f6bdfa" title="Allocate a topology context.">hwloc_topology_init</a>(&amp;topology);
205
 
 
206
 
        <span class="comment">/* ... Optionally, put detection configuration here to e.g. ignore some</span>
207
 
<span class="comment">           objects types, define a synthetic topology, etc....  The default is</span>
208
 
<span class="comment">           to detect all the objects of the machine that the caller is allowed</span>
209
 
<span class="comment">           to access.</span>
210
 
<span class="comment">           See Configure Topology Detection.  */</span>
211
 
 
212
 
        <span class="comment">/* Perform the topology detection.  */</span>
213
 
        <a class="code" href="group__hwlocality__creation.html#gabdf58d87ad77f6615fccdfe0535ff826" title="Build the actual topology.">hwloc_topology_load</a>(topology);
214
 
 
215
 
 
216
 
        <span class="comment">/* Optionally, get some additional topology information</span>
217
 
<span class="comment">         * in case we need the topology depth later.</span>
218
 
<span class="comment">         */</span>
219
 
        <span class="keywordtype">unsigned</span> topodepth = <a class="code" href="group__hwlocality__information.html#ga3cc2255e237b751a6c8efa8703b3daf5" title="Get the depth of the hierachical tree of objects.">hwloc_topology_get_depth</a>(topology);
220
 
 
221
 
 
222
 
        <span class="comment">/* Walk the topology with an array style, from level 0 (always the</span>
223
 
<span class="comment">         * system level) to the lowest level (always the proc level). */</span>
224
 
        <span class="keywordtype">int</span> depth, i;
225
 
        <span class="keywordtype">char</span> <span class="keywordtype">string</span>[128];
226
 
        <span class="keywordflow">for</span> (depth = 0; depth &lt; topodepth; depth++) {
227
 
                <span class="keywordflow">for</span> (i = 0; i &lt; <a class="code" href="group__hwlocality__information.html#gab17065e3d53455973844568d9f21c72c" title="Returns the width of level at depth depth.">hwloc_get_nbobjs_by_depth</a>(topology, depth); i++) {
228
 
                        <a class="code" href="group__hwlocality__conversion.html#ga612dc210053b65d2466ac7ad39db92a4" title="Stringify a given topology object into a human-readable form.">hwloc_obj_snprintf</a>(<span class="keywordtype">string</span>, <span class="keyword">sizeof</span>(<span class="keywordtype">string</span>), topology,
229
 
                                        <a class="code" href="group__hwlocality__traversal.html#gabf8a98ad085460a4982cc7b74c344b71" title="Returns the topology object at index index from depth depth.">hwloc_get_obj_by_depth</a>(topology, depth, i), <span class="stringliteral">&quot;#&quot;</span>, 0);
230
 
                        printf(<span class="stringliteral">&quot;%s\n&quot;</span>, <span class="keywordtype">string</span>);
231
 
                }
 
200
    <span class="keywordtype">int</span> depth, i;
 
201
    <span class="keywordtype">char</span> <span class="keywordtype">string</span>[128];
 
202
    <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> topodepth;
 
203
    <a class="code" href="group__hwlocality__topology.html#ga9d1e76ee15a7dee158b786c30b6a6e38" title="Topology context.">hwloc_topology_t</a> topology;
 
204
    <a class="code" href="group__hwlocality__cpuset.html#ga7366332f7090f5b54d4b25a0c2c4b411" title="Set of CPUs represented as an opaque pointer to an internal bitmask.">hwloc_cpuset_t</a> cpuset;
 
205
    <a class="code" href="structhwloc__obj.html" title="Structure of a topology object.">hwloc_obj_t</a> obj;
 
206
 
 
207
    <span class="comment">/* Allocate and initialize topology object. */</span>
 
208
    <a class="code" href="group__hwlocality__creation.html#ga03fd4a16d8b9ee1ffc32b25fd2f6bdfa" title="Allocate a topology context.">hwloc_topology_init</a>(&amp;topology);
 
209
 
 
210
    <span class="comment">/* ... Optionally, put detection configuration here to e.g. ignore</span>
 
211
<span class="comment">       some objects types, define a synthetic topology, etc....  </span>
 
212
<span class="comment"></span>
 
213
<span class="comment">       The default is to detect all the objects of the machine that</span>
 
214
<span class="comment">       the caller is allowed to access.  See Configure Topology</span>
 
215
<span class="comment">       Detection. */</span>
 
216
 
 
217
    <span class="comment">/* Perform the topology detection. */</span>
 
218
    <a class="code" href="group__hwlocality__creation.html#gabdf58d87ad77f6615fccdfe0535ff826" title="Build the actual topology.">hwloc_topology_load</a>(topology);
 
219
 
 
220
    <span class="comment">/* Optionally, get some additional topology information</span>
 
221
<span class="comment">       in case we need the topology depth later. */</span>
 
222
    topodepth = <a class="code" href="group__hwlocality__information.html#ga3cc2255e237b751a6c8efa8703b3daf5" title="Get the depth of the hierachical tree of objects.">hwloc_topology_get_depth</a>(topology);
 
223
 
 
224
    <span class="comment">/* Walk the topology with an array style, from level 0 (always the</span>
 
225
<span class="comment">       system level) to the lowest level (always the proc level). */</span>
 
226
    <span class="keywordflow">for</span> (depth = 0; depth &lt; topodepth; depth++) {
 
227
        printf(<span class="stringliteral">&quot;*** Objects at level %d\n&quot;</span>, depth);
 
228
        <span class="keywordflow">for</span> (i = 0; i &lt; <a class="code" href="group__hwlocality__information.html#gab17065e3d53455973844568d9f21c72c" title="Returns the width of level at depth depth.">hwloc_get_nbobjs_by_depth</a>(topology, depth); 
 
229
             i++) {
 
230
            <a class="code" href="group__hwlocality__conversion.html#ga612dc210053b65d2466ac7ad39db92a4" title="Stringify a given topology object into a human-readable form.">hwloc_obj_snprintf</a>(<span class="keywordtype">string</span>, <span class="keyword">sizeof</span>(<span class="keywordtype">string</span>), topology,
 
231
                       <a class="code" href="group__hwlocality__traversal.html#gabf8a98ad085460a4982cc7b74c344b71" title="Returns the topology object at index index from depth depth.">hwloc_get_obj_by_depth</a>(topology, depth, i),
 
232
                       <span class="stringliteral">&quot;#&quot;</span>, 0);
 
233
            printf(<span class="stringliteral">&quot;Index %d: %s\n&quot;</span>, i, <span class="keywordtype">string</span>);
232
234
        }
233
 
 
234
 
        <span class="comment">/* Walk the topology with a tree style.  */</span>
235
 
        print_children(topology, <a class="code" href="group__hwlocality__helper__traversal__basic.html#gab39658e42f1046db0f8870a0d0ba9f42" title="Returns the top-object of the topology-tree. Its type is HWLOC_OBJ_SYSTEM.">hwloc_get_system_obj</a>(topology), 0);
236
 
 
237
 
 
238
 
        <span class="comment">/* Print the number of sockets.  */</span>
239
 
        depth = <a class="code" href="group__hwlocality__information.html#ga8bec782e21be313750da70cf7428b374" title="Returns the depth of objects of type type.">hwloc_get_type_depth</a>(topology, <a class="code" href="group__hwlocality__types.html#ggacd37bb612667dc437d66bfb175a8dc55a1ac6e07775ae4324b3fe9dbd72c785ec" title="Socket, physical package, or chip. In the physical meaning, i.e. that you can add...">HWLOC_OBJ_SOCKET</a>);
240
 
        <span class="keywordflow">if</span> (depth == <a class="code" href="group__hwlocality__information.html#ga9e86ce528f626330de2da7adb6c4e02e" title="No object of given type exists in the topology.">HWLOC_TYPE_DEPTH_UNKNOWN</a>)
241
 
                printf(<span class="stringliteral">&quot;The number of sockets is unknown\n&quot;</span>);
242
 
        <span class="keywordflow">else</span>
243
 
                printf(<span class="stringliteral">&quot;%u socket(s)\n&quot;</span>, <a class="code" href="group__hwlocality__information.html#gab17065e3d53455973844568d9f21c72c" title="Returns the width of level at depth depth.">hwloc_get_nbobjs_by_depth</a>(topology, depth));
244
 
 
245
 
 
246
 
        <span class="comment">/* Find out where cores are, or else smaller sets of CPUs if the OS</span>
247
 
<span class="comment">         * doesn&apos;t have the notion of core. */</span>
248
 
        depth = <a class="code" href="group__hwlocality__helper__types.html#gaa0835c86ef2ce8c62637d61a1cf134f9" title="Returns the depth of objects of type type or below.">hwloc_get_type_or_below_depth</a>(topology, <a class="code" href="group__hwlocality__types.html#ggacd37bb612667dc437d66bfb175a8dc55ac793958f330bca371aa1535de8aff45f" title="Core. A computation unit (may be shared by several logical processors).">HWLOC_OBJ_CORE</a>);
249
 
 
250
 
        <span class="comment">/* Get last one.  */</span>
251
 
        <a class="code" href="structhwloc__obj.html" title="Structure of a topology object.">hwloc_obj_t</a> obj = <a class="code" href="group__hwlocality__traversal.html#gabf8a98ad085460a4982cc7b74c344b71" title="Returns the topology object at index index from depth depth.">hwloc_get_obj_by_depth</a>(topology, depth, <a class="code" href="group__hwlocality__information.html#gab17065e3d53455973844568d9f21c72c" title="Returns the width of level at depth depth.">hwloc_get_nbobjs_by_depth</a>(topology, depth) - 1);
252
 
        <span class="keywordflow">if</span> (!obj)
253
 
                <span class="keywordflow">return</span> 0;
254
 
 
255
 
        <span class="comment">/* Get a copy of its cpuset that we may modify.  */</span>
256
 
        <a class="code" href="group__hwlocality__cpuset.html#ga7366332f7090f5b54d4b25a0c2c4b411" title="Set of CPUs represented as an opaque pointer to an internal bitmask.">hwloc_cpuset_t</a> cpuset = <a class="code" href="group__hwlocality__cpuset.html#ga19d8c163e4834ba69c808560aa5a89b3" title="Duplicate CPU set set by allocating a new CPU set and copying its contents.">hwloc_cpuset_dup</a>(obj-&gt;<a class="code" href="structhwloc__obj.html#a67925e0f2c47f50408fbdb9bddd0790f" title="CPUs covered by this object.">cpuset</a>);
257
 
 
258
 
        <span class="comment">/* Get only one logical processor (in case the core is SMT/hyperthreaded).  */</span>
 
235
    }
 
236
 
 
237
    <span class="comment">/* Walk the topology with a tree style. */</span>
 
238
    printf(<span class="stringliteral">&quot;*** Printing overall tree\n&quot;</span>);
 
239
    print_children(topology, <a class="code" href="group__hwlocality__helper__traversal__basic.html#gab39658e42f1046db0f8870a0d0ba9f42" title="Returns the top-object of the topology-tree. Its type is HWLOC_OBJ_SYSTEM.">hwloc_get_system_obj</a>(topology), 0);
 
240
 
 
241
    <span class="comment">/* Print the number of sockets. */</span>
 
242
    depth = <a class="code" href="group__hwlocality__information.html#ga8bec782e21be313750da70cf7428b374" title="Returns the depth of objects of type type.">hwloc_get_type_depth</a>(topology, <a class="code" href="group__hwlocality__types.html#ggacd37bb612667dc437d66bfb175a8dc55a1ac6e07775ae4324b3fe9dbd72c785ec" title="Socket, physical package, or chip. In the physical meaning, i.e. that you can add...">HWLOC_OBJ_SOCKET</a>);
 
243
    <span class="keywordflow">if</span> (depth == <a class="code" href="group__hwlocality__information.html#ga9e86ce528f626330de2da7adb6c4e02e" title="No object of given type exists in the topology.">HWLOC_TYPE_DEPTH_UNKNOWN</a>) {
 
244
        printf(<span class="stringliteral">&quot;*** The number of sockets is unknown\n&quot;</span>);
 
245
    } <span class="keywordflow">else</span> {
 
246
        printf(<span class="stringliteral">&quot;*** %u socket(s)\n&quot;</span>, 
 
247
               <a class="code" href="group__hwlocality__information.html#gab17065e3d53455973844568d9f21c72c" title="Returns the width of level at depth depth.">hwloc_get_nbobjs_by_depth</a>(topology, depth));
 
248
    }
 
249
 
 
250
    <span class="comment">/* Find out where cores are, or else smaller sets of CPUs if </span>
 
251
<span class="comment">       the OS doesn&apos;t have the notion of a &quot;core&quot;. */</span>
 
252
    depth = <a class="code" href="group__hwlocality__helper__types.html#gaa0835c86ef2ce8c62637d61a1cf134f9" title="Returns the depth of objects of type type or below.">hwloc_get_type_or_below_depth</a>(topology, <a class="code" href="group__hwlocality__types.html#ggacd37bb612667dc437d66bfb175a8dc55ac793958f330bca371aa1535de8aff45f" title="Core. A computation unit (may be shared by several logical processors).">HWLOC_OBJ_CORE</a>);
 
253
 
 
254
    <span class="comment">/* Get last level. */</span>
 
255
    obj = <a class="code" href="group__hwlocality__traversal.html#gabf8a98ad085460a4982cc7b74c344b71" title="Returns the topology object at index index from depth depth.">hwloc_get_obj_by_depth</a>(topology, depth, 
 
256
                   <a class="code" href="group__hwlocality__information.html#gab17065e3d53455973844568d9f21c72c" title="Returns the width of level at depth depth.">hwloc_get_nbobjs_by_depth</a>(topology, depth) - 1);
 
257
    <span class="keywordflow">if</span> (obj) {
 
258
        <span class="comment">/* Get a copy of its cpuset that we may modify. */</span>
 
259
        cpuset = <a class="code" href="group__hwlocality__cpuset.html#ga19d8c163e4834ba69c808560aa5a89b3" title="Duplicate CPU set set by allocating a new CPU set and copying its contents.">hwloc_cpuset_dup</a>(obj-&gt;<a class="code" href="structhwloc__obj.html#a67925e0f2c47f50408fbdb9bddd0790f" title="CPUs covered by this object.">cpuset</a>);
 
260
    
 
261
        <span class="comment">/* Get only one logical processor (in case the core is</span>
 
262
<span class="comment">           SMT/hyperthreaded). */</span>
259
263
        <a class="code" href="group__hwlocality__cpuset.html#ga548a6620cce008fc5b1e2110d25135fe" title="Keep a single CPU among those set in CPU set set.">hwloc_cpuset_singlify</a>(cpuset);
260
264
 
261
 
        <span class="comment">/* And try to bind ourself there.  */</span>
 
265
        <span class="comment">/* And try to bind ourself there. */</span>
262
266
        <span class="keywordflow">if</span> (<a class="code" href="group__hwlocality__binding.html#ga47053da286384d86ec3e4fb3fe148dae" title="Bind current process or thread on cpus given in cpuset set.">hwloc_set_cpubind</a>(topology, cpuset, 0)) {
263
 
                <span class="keywordtype">char</span> *str = NULL;
264
 
                <a class="code" href="group__hwlocality__cpuset.html#ga29160016d2e89318b5db99046d93dc0a" title="Stringify a cpuset into a newly allocated string.">hwloc_cpuset_asprintf</a>(&amp;str, obj-&gt;<a class="code" href="structhwloc__obj.html#a67925e0f2c47f50408fbdb9bddd0790f" title="CPUs covered by this object.">cpuset</a>);
265
 
                printf(<span class="stringliteral">&quot;Couldn&apos;t bind to cpuset %s\n&quot;</span>, str);
266
 
                free(str);
 
267
            <span class="keywordtype">char</span> *str;
 
268
            <a class="code" href="group__hwlocality__cpuset.html#ga29160016d2e89318b5db99046d93dc0a" title="Stringify a cpuset into a newly allocated string.">hwloc_cpuset_asprintf</a>(&amp;str, obj-&gt;<a class="code" href="structhwloc__obj.html#a67925e0f2c47f50408fbdb9bddd0790f" title="CPUs covered by this object.">cpuset</a>);
 
269
            printf(<span class="stringliteral">&quot;Couldn&apos;t bind to cpuset %s\n&quot;</span>, str);
 
270
            free(str);
267
271
        }
268
272
 
269
273
        <span class="comment">/* Free our cpuset copy */</span>
270
274
        <a class="code" href="group__hwlocality__cpuset.html#gaf5d5a9e082a43f8311fdcff55e611b23" title="Free CPU set set.">hwloc_cpuset_free</a>(cpuset);
271
 
 
272
 
        <span class="comment">/* Destroy topology object.  */</span>
273
 
        <a class="code" href="group__hwlocality__creation.html#ga9f34a640b6fd28d23699d4d084667b15" title="Terminate and free a topology context.">hwloc_topology_destroy</a>(topology);
274
 
 
275
 
        <span class="keywordflow">return</span> 0;
 
275
    }
 
276
 
 
277
    <span class="comment">/* Destroy topology object. */</span>
 
278
    <a class="code" href="group__hwlocality__creation.html#ga9f34a640b6fd28d23699d4d084667b15" title="Terminate and free a topology context.">hwloc_topology_destroy</a>(topology);
 
279
 
 
280
    <span class="keywordflow">return</span> 0;
276
281
}
 
282
</pre></div><p>hwloc provides a <code>pkg-config</code> executable to obtain relevant compiler and linker flags. For example, it can be used thusly to compile applications that utilize the hwloc library (assuming GNU Make):</p>
 
283
<div class="fragment"><pre class="fragment">
 
284
CFLAGS += $(pkg-config --cflags hwloc)
 
285
LDLIBS += $(pkg-config --libs hwloc)
 
286
cc hwloc-hello.c $(CFLAGS) -o hwloc-hello $(LDLIBS)
 
287
</pre></div><p>On a machine with 4GB of RAM and 2 processor sockets -- each socket of which has two processor cores -- the output from running <code>hwloc-hello</code> could be something like the following:</p>
 
288
<div class="fragment"><pre class="fragment">
 
289
shell$ ./hwloc-hello
 
290
*** Objects at level 0
 
291
Index 0: System(3938MB)
 
292
*** Objects at level 1
 
293
Index 0: Socket#0
 
294
Index 1: Socket#1
 
295
*** Objects at level 2
 
296
Index 0: Core#0
 
297
Index 1: Core#1
 
298
Index 2: Core#3
 
299
Index 3: Core#2
 
300
*** Objects at level 3
 
301
Index 0: P#0
 
302
Index 1: P#1
 
303
Index 2: P#2
 
304
Index 3: P#3
 
305
*** Printing overall tree
 
306
System(3938MB)
 
307
  Socket#0
 
308
    Core#0
 
309
      P#0
 
310
    Core#1
 
311
      P#1
 
312
  Socket#1
 
313
    Core#3
 
314
      P#2
 
315
    Core#2
 
316
      P#3
 
317
*** 2 socket(s)
 
318
shell$ 
277
319
</pre></div> 
278
320
</div><div class="section" id="bugs">
279
321
 <h2><a class="anchor" id="bugs">
287
329
<p>libtopology was initially developed by the INRIA Runtime Team-Project (<a href="http://runtime.bordeaux.inria.fr/">http://runtime.bordeaux.inria.fr/</a>) (headed by Raymond Namyst (<a href="http://dept-info.labri.fr/~namyst/">http://dept-info.labri.fr/~namyst/</a>). 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>
288
330
 
289
331
</div>
290
 
 </div>
291
 
<hr size="1"/><address style="text-align: right;"><small>Generated on Thu Nov 5 09:58:42 2009 for Hardware Locality (hwloc) by&nbsp;
 
332
<h2><a class="anchor" id="glossary">
 
333
Glossary</a></h2>
 
334
<dl>
 
335
<dt>Object </dt>
 
336
<dd><p class="startdd">Interesting kind of part of the system, such as a Core, a Cache, a Memory node, etc. The different types detected by hwloc are detailed in the <a class="el" href="group__hwlocality__types.html#gacd37bb612667dc437d66bfb175a8dc55" title="Type of topology object.">hwloc_obj_type_t</a> enumeration.</p>
 
337
<p>They are topologically sorted by CPU set into a tree whose root is the System object (which always exists). </p>
 
338
<p class="enddd"></p>
 
339
</dd>
 
340
<dt>CPU set </dt>
 
341
<dd><p class="startdd">The set of logical processors logically included in an object (if any). This term does <em>not</em> have any relation to an operating system ``CPU set.''</p>
 
342
<p class="enddd"></p>
 
343
</dd>
 
344
<dt>Father object </dt>
 
345
<dd><p class="startdd">The object logically containing the current object, for example because its CPU set includes the CPU set of the current object.</p>
 
346
<p class="enddd"></p>
 
347
</dd>
 
348
<dt>Children object(s) </dt>
 
349
<dd><p class="startdd">The object (or objects) contained in the current object because their CPU set is included in the CPU set of the current object.</p>
 
350
<p class="enddd"></p>
 
351
</dd>
 
352
<dt>Arity </dt>
 
353
<dd><p class="startdd">The number of children of an object.</p>
 
354
<p class="enddd"></p>
 
355
</dd>
 
356
<dt>Sibling objects </dt>
 
357
<dd><p class="startdd">Objects of the same type which have the same father.</p>
 
358
<p class="enddd"></p>
 
359
</dd>
 
360
<dt>Sibling rank </dt>
 
361
<dd><p class="startdd">Index to uniquely identify objects of the same type which have the same father, and is always in the range [0, fathers_arity).</p>
 
362
<p class="enddd"></p>
 
363
</dd>
 
364
<dt>Cousin objects </dt>
 
365
<dd><p class="startdd">Objects of the same type as the current object.</p>
 
366
<p class="enddd"></p>
 
367
</dd>
 
368
<dt>Level </dt>
 
369
<dd><p class="startdd">Set of objects of the same type.</p>
 
370
<p class="enddd"></p>
 
371
</dd>
 
372
<dt>OS index </dt>
 
373
<dd><p class="startdd">The index that the operating system (OS) uses to identify the object. This may be completely arbitrary, or it may depend on the BIOS configuration.</p>
 
374
<p class="enddd"></p>
 
375
</dd>
 
376
<dt>Depth </dt>
 
377
<dd><p class="startdd">Nesting level in the object tree, starting from the 0th object (i.e., the System object).</p>
 
378
<p class="enddd"></p>
 
379
</dd>
 
380
<dt>Logical index </dt>
 
381
<dd><p class="startdd">Index to uniquely identify objects of the same type. It is generally used to express proximity. This index is always linear and in the range [0, num_objs_same_type_same_level). Think of it as ``cousin rank.''</p>
 
382
<p class="enddd"></p>
 
383
</dd>
 
384
</dl>
 
385
<p>The following diagram can help to understand the vocabulary of the relationships by showing the example of a machine with two dual core sockets (with no hardware threads); thus, a topology with 4 levels.</p>
 
386
<div align="center">
 
387
<img src="diagram.png" alt="diagram.png"/>
 
388
</div>
 
389
 <p>It should be noted that for Processor objects, the logical index -- as computed linearly by hwloc -- is not the same as the OS index. </p>
 
390
</div>
 
391
<hr size="1"/><address style="text-align: right;"><small>Generated on Tue Nov 24 11:55:11 2009 for Hardware Locality (hwloc) by&nbsp;
292
392
<a href="http://www.doxygen.org/index.html">
293
393
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.1 </small></address>
294
394
</body>