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
|
<!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): Upgrading to the hwloc 2.0 API</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">Upgrading to the hwloc 2.0 API</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>See <a class="el" href="a00382.html#faq5">Compatibility between hwloc versions</a> for detecting the hwloc version that you are compiling and/or running against.</p>
<h1><a class="anchor" id="upgrade_to_api_2x_memory"></a>
New Organization of NUMA nodes and Memory</h1>
<h2><a class="anchor" id="upgrade_to_api_2x_memory_children"></a>
Memory children</h2>
<p>In hwloc v1.x, NUMA nodes were inside the tree, for instance Packages contained 2 NUMA nodes which contained a L3 and several cache.</p>
<p>Starting with hwloc v2.0, NUMA nodes are not in the main tree anymore. They are attached under objects as <em>Memory Children</em> on the side of normal children. This memory children list starts at <code>obj->memory_first_child</code> and its size is <code>obj->memory_arity</code>. Hence there can now exist two local NUMA nodes, for instance on Intel Xeon Phi processors.</p>
<p>The normal list of children (starting at <code>obj->first_child</code>, ending at <code>obj->last_child</code>, of size <code>obj->arity</code>, and available as the array <code>obj->children</code>) now only contains CPU-side objects: PUs, Cores, Packages, Caches, Groups, Machine and System. <a class="el" href="a00178.html#ga761c8e824b0ffaa8ea416c761fd70bdc" title="Return the next child.">hwloc_get_next_child()</a> may still be used to iterate over all children of all lists.</p>
<p>Hence the CPU-side hierarchy is built using normal children, while memory is attached to that hierarchy depending on its affinity.</p>
<h2><a class="anchor" id="upgrade_to_api_2x_memory_examples"></a>
Examples</h2>
<ul>
<li>
<p class="startli">a UMA machine with 2 packages and a single NUMA node is now modeled as a "Machine" object with two "Package" children and one "NUMANode" memory children (displayed first in lstopo below): </p><pre class="fragment">Machine (1024MB total)
NUMANode L#0 (P#0 1024MB)
Package L#0
Core L#0 + PU L#0 (P#0)
Core L#1 + PU L#1 (P#1)
Package L#1
Core L#2 + PU L#2 (P#2)
Core L#3 + PU L#3 (P#3)
</pre> <p class="endli"></p>
</li>
<li>
<p class="startli">a machine with 2 packages with one NUMA node and 2 cores in each is now: </p><pre class="fragment">Machine (2048MB total)
Package L#0
NUMANode L#0 (P#0 1024MB)
Core L#0 + PU L#0 (P#0)
Core L#1 + PU L#1 (P#1)
Package L#1
NUMANode L#1 (P#1 1024MB)
Core L#2 + PU L#2 (P#2)
Core L#3 + PU L#3 (P#3)
</pre> <p class="endli"></p>
</li>
<li>
<p class="startli">if there are two NUMA nodes per package, a Group object may be added to keep cores together with their local NUMA node: </p><pre class="fragment">Machine (4096MB total)
Package L#0
Group0 L#0
NUMANode L#0 (P#0 1024MB)
Core L#0 + PU L#0 (P#0)
Core L#1 + PU L#1 (P#1)
Group0 L#1
NUMANode L#1 (P#1 1024MB)
Core L#2 + PU L#2 (P#2)
Core L#3 + PU L#3 (P#3)
Package L#1
[...]
</pre> <p class="endli"></p>
</li>
<li>
if the platform has L3 caches whose localities are identical to NUMA nodes, Groups aren't needed: <pre class="fragment">Machine (4096MB total)
Package L#0
L3 L#0 (16MB)
NUMANode L#0 (P#0 1024MB)
Core L#0 + PU L#0 (P#0)
Core L#1 + PU L#1 (P#1)
L3 L#1 (16MB)
NUMANode L#1 (P#1 1024MB)
Core L#2 + PU L#2 (P#2)
Core L#3 + PU L#3 (P#3)
Package L#1
[...]
</pre> </li>
</ul>
<h2><a class="anchor" id="upgrade_to_api_2x_numa_level"></a>
NUMA level and depth</h2>
<p>NUMA nodes are not in "main" tree of normal objects anymore. Hence, they don't have a meaningful depth anymore (like I/O and Misc objects). They have a virtual (negative) depth (<a class="el" href="a00167.html#ggaf4e663cf42bbe20756b849c6293ef575a245c34ec9884c2cf5de5049b2153ed9c" title="Virtual depth for NUMA nodes.">HWLOC_TYPE_DEPTH_NUMANODE</a>) so that functions manipulating depths and level still work, and so that we can still iterate over the level of NUMA nodes just like for any other level.</p>
<p>For instance we can still use lines such as </p><pre class="fragment">int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
hwloc_obj_t obj = hwloc_get_obj_by_type(topology, HWLOC_OBJ_NUMANODE, 4);
hwloc_obj_t node = hwloc_get_next_obj_by_depth(topology, HWLOC_TYPE_DEPTH_NUMANODE, prev);
</pre><p>The NUMA depth should not be compared with others. An unmodified code that still compares NUMA and Package depths (to find out whether Packages contain NUMA or the contrary) would now always assume Packages contain NUMA (because the NUMA depth is negative).</p>
<p>However, the depth of the Normal parents of NUMA nodes may be used instead. In the last example above, NUMA nodes are attached to L3 caches, hence one may compare the depth of Packages and L3 to find out that NUMA nodes are contained in Packages. This depth of parents may be retrieved with <a class="el" href="a00167.html#gae85786340b88e24835f8c403a1e2e54b" title="Return the depth of parents where memory objects are attached.">hwloc_get_memory_parents_depth()</a>. However, this function may return <a class="el" href="a00167.html#ggaf4e663cf42bbe20756b849c6293ef575ae99465995cacde6c210d5fc2e409798c" title="Objects of given type exist at different depth in the topology (only for Groups).">HWLOC_TYPE_DEPTH_MULTIPLE</a> on future platforms if NUMA nodes are attached to different levels.</p>
<h2><a class="anchor" id="upgrade_to_api_2x_memory_find"></a>
Finding Local NUMA nodes and looking at Children and Parents</h2>
<p>Applications that walked up/down to find NUMANode parent/children must now be updated. Instead of looking directly for a NUMA node, one should now look for an object that has some memory children. NUMA node(s) will be attached there. For instance, when looking for a NUMA node above a given core <code>core</code>: </p><pre class="fragment">hwloc_obj_t parent = core->parent;
while (parent && !parent->memory_arity)
parent = parent->parent; /* no memory child, walk up */
if (parent)
/* use parent->memory_first_child (and its siblings if there are multiple local NUMA nodes) */
</pre><p>The list of local NUMA nodes (usually a single one) is also described by the <code>nodeset</code> attribute of each object (which contains the physical indexes of these nodes). Iterating over the NUMA level is also an easy way to find local NUMA nodes: </p><pre class="fragment">hwloc_obj_t tmp = NULL;
while ((tmp = hwloc_get_next_obj_by_type(topology, HWLOC_OBJ_NUMANODE, tmp)) != NULL) {
if (hwloc_bitmap_isset(obj->nodeset, tmp->os_index))
/* tmp is a NUMA node local to obj, use it */
}
</pre><p>Similarly finding objects that are close to a given NUMA nodes should be updated too. Instead of looking at the NUMA node parents/children, one should now find a Normal parent above that NUMA node, and then look at its parents/children as usual: </p><pre class="fragment">hwloc_obj_t tmp = obj->parent;
while (hwloc_obj_type_is_memory(tmp))
tmp = tmp->parent;
/* now use tmp instead of obj */
</pre><p>To avoid such hwloc v2.x-specific and NUMA-specific cases in the code, a <b>generic lookup for any kind of object, including NUMA nodes</b>, might also be implemented by iterating over a level. For instance finding an object of type <code>type</code> which either contains or is included in object <code>obj</code> can be performed by traversing the level of that type and comparing CPU sets: </p><pre class="fragment">hwloc_obj_t tmp = NULL;
while ((tmp = hwloc_get_next_obj_by_type(topology, type, tmp)) != NULL) {
if (hwloc_bitmap_intersects(tmp->cpuset, obj->cpuset))
/* tmp matches, use it */
}
</pre><p> <b> This generic lookup works whenever <code>type</code> or <code>obj</code> are Normal or Memory objects since both have CPU sets. Moreover, it is compatible with the hwloc v1.x API. </b></p>
<h1><a class="anchor" id="upgrade_to_api_2x_children"></a>
4 Kinds of Objects and Children</h1>
<h2><a class="anchor" id="upgrade_to_api_2x_io_misc_children"></a>
I/O and Misc children</h2>
<p>I/O children are not in the main object children list anymore either. They are in the list starting at <code>obj->io_first_child</code> and its size is <code>obj->io_arity</code>.</p>
<p>Misc children are not in the main object children list anymore. They are in the list starting at <code>obj->misc_first_child</code> and its size is <code>obj->misc_arity</code>.</p>
<p>See <a class="el" href="a00220.html" title="Structure of a topology object.">hwloc_obj</a> for details about children lists.</p>
<p><a class="el" href="a00178.html#ga761c8e824b0ffaa8ea416c761fd70bdc" title="Return the next child.">hwloc_get_next_child()</a> may still be used to iterate over all children of all lists.</p>
<h2><a class="anchor" id="upgrade_to_api_2x_kinds_subsec"></a>
Kinds of objects</h2>
<p>Given the above, objects may now be of 4 kinds: </p><ul>
<li>
Normal (everything not listed below, including Machine, Package, Core, PU, CPU Caches, etc); </li>
<li>
Memory (currently NUMA nodes or Memory-side Caches), attached to parents as Memory children; </li>
<li>
I/O (Bridges, PCI and OS devices), attached to parents as I/O children; </li>
<li>
Misc objects, attached to parents as Misc children. </li>
</ul>
<p>See <a class="el" href="a00220.html" title="Structure of a topology object.">hwloc_obj</a> for details about children lists.</p>
<p>For a given object type, the kind may be found with <a class="el" href="a00175.html#ga52ef38431eba383b048b98c669b59a16" title="Check whether an object type is Normal.">hwloc_obj_type_is_normal()</a>, <a class="el" href="a00175.html#ga1d074390c8a3dc3088d84f73fb73f966" title="Check whether an object type is Memory.">hwloc_obj_type_is_memory()</a>, <a class="el" href="a00175.html#ga52ef38431eba383b048b98c669b59a16" title="Check whether an object type is Normal.">hwloc_obj_type_is_normal()</a>, or comparing with <a class="el" href="a00164.html#ggacd37bb612667dc437d66bfb175a8dc55a19f8a6953fa91efc76bcbcdf2d22de4d" title="Miscellaneous objects (filtered out by default). Objects without particular meaning,...">HWLOC_OBJ_MISC</a>.</p>
<p>Normal and Memory objects have (non-NULL) CPU sets and nodesets, while I/O and Misc objects don't have any sets (they are NULL).</p>
<h1><a class="anchor" id="upgrade_to_api_2x_cache"></a>
HWLOC_OBJ_CACHE replaced</h1>
<p>Instead of a single HWLOC_OBJ_CACHE, there are now 8 types <a class="el" href="a00164.html#ggacd37bb612667dc437d66bfb175a8dc55a56389b8eb2e2f74f288bb657c4e72140" title="Level 1 Data (or Unified) Cache.">HWLOC_OBJ_L1CACHE</a>, ..., <a class="el" href="a00164.html#ggacd37bb612667dc437d66bfb175a8dc55a67194c9de5e3e581c64c11d2eb1c109d" title="Level 5 Data (or Unified) Cache.">HWLOC_OBJ_L5CACHE</a>, <a class="el" href="a00164.html#ggacd37bb612667dc437d66bfb175a8dc55afa834a85d9e53836cf0db6d0bd8329b4" title="Level 1 instruction Cache (filtered out by default).">HWLOC_OBJ_L1ICACHE</a>, ..., <a class="el" href="a00164.html#ggacd37bb612667dc437d66bfb175a8dc55ac22850c717f07bf7ffb316fadd08d218" title="Level 3 instruction Cache (filtered out by default).">HWLOC_OBJ_L3ICACHE</a>.</p>
<p>Cache object attributes are unchanged.</p>
<p><a class="el" href="a00179.html#ga347a289a3956147fcc1f44feb5e6960b" title="Find the depth of cache objects matching cache level and type.">hwloc_get_cache_type_depth()</a> is not needed to disambiguate cache types anymore since new types can be passed to <a class="el" href="a00167.html#ga8bec782e21be313750da70cf7428b374" title="Returns the depth of objects of type type.">hwloc_get_type_depth()</a> without ever getting <a class="el" href="a00167.html#ggaf4e663cf42bbe20756b849c6293ef575ae99465995cacde6c210d5fc2e409798c" title="Objects of given type exist at different depth in the topology (only for Groups).">HWLOC_TYPE_DEPTH_MULTIPLE</a> anymore.</p>
<p><a class="el" href="a00175.html#ga2ed589bea28711e80b92066510a5607d" title="Check whether an object type is a CPU Cache (Data, Unified or Instruction).">hwloc_obj_type_is_cache()</a>, <a class="el" href="a00175.html#ga395e48cd221d107e5891689624e1aec4" title="Check whether an object type is a CPU Data or Unified Cache.">hwloc_obj_type_is_dcache()</a> and <a class="el" href="a00175.html#ga8abcee67b9b074332c1866405a3648a9" title="Check whether an object type is a CPU Instruction Cache,.">hwloc_obj_type_is_icache()</a> may be used to check whether a given type is a cache, data/unified cache or instruction cache.</p>
<h1><a class="anchor" id="upgrade_to_api_2x_allowed"></a>
allowed_cpuset and allowed_nodeset only in the main topology</h1>
<p>Objects do not have <code>allowed_cpuset</code> and <code>allowed_nodeset</code> anymore. They are only available for the entire topology using <a class="el" href="a00182.html#ga517d5d68ec9f24583d8933aab713be8e" title="Get allowed CPU set.">hwloc_topology_get_allowed_cpuset()</a> and <a class="el" href="a00182.html#ga21a4d7237a11e76b912ed4524ab78cbd" title="Get allowed node set.">hwloc_topology_get_allowed_nodeset()</a>.</p>
<p>As usual, those are only needed when the INCLUDE_DISALLOWED topology flag is given, which means disallowed objects are kept in the topology. If so, one may find out whether some PUs inside an object is allowed by checking </p><pre class="fragment">hwloc_bitmap_intersects(obj->cpuset, hwloc_topology_get_allowed_cpuset(topology))
</pre><p> Replace cpusets with nodesets for NUMA nodes. To find out which ones, replace intersects() with and() to get the actual intersection.</p>
<h1><a class="anchor" id="upgrade_to_api_2x_depth"></a>
Object depths are now signed int</h1>
<p><code>obj->depth</code> as well as depths given to functions such as <a class="el" href="a00167.html#ga391f6b2613f0065673eaa4069b93d4e0" title="Returns the topology object at logical index idx from depth depth.">hwloc_get_obj_by_depth()</a> or returned by <a class="el" href="a00167.html#gae54d1782ca9b54bea915f5c18a9158fa" title="Get the depth of the hierarchical tree of objects.">hwloc_topology_get_depth()</a> are now <b>signed int</b>.</p>
<p>Other depth such as cache-specific depth attribute are still unsigned.</p>
<h1><a class="anchor" id="upgrade_to_api_2x_memory_attrs"></a>
Memory attributes become NUMANode-specific</h1>
<p>Memory attributes such as <code>obj->memory.local_memory</code> are now only available in NUMANode-specific attributes in <code>obj->attr->numanode.local_memory</code>.</p>
<p><code>obj->memory.total_memory</code> is available in all objects as <code>obj->total_memory</code>.</p>
<p>See <a class="el" href="a00228.html" title="NUMA node-specific Object Attributes.">hwloc_obj_attr_u::hwloc_numanode_attr_s</a> and <a class="el" href="a00220.html" title="Structure of a topology object.">hwloc_obj</a> for details.</p>
<h1><a class="anchor" id="upgrade_to_api_2x_config"></a>
Topology configuration changes</h1>
<p>The old ignoring API as well as several configuration flags are replaced with the new filtering API, see <a class="el" href="a00173.html#gad894e70f15f8d4aada7be8d1aba38b7e" title="Set the filtering for the given object type.">hwloc_topology_set_type_filter()</a> and its variants, and <a class="el" href="a00173.html#ga9a5a1f0140cd1952544477833733195b" title="Type filtering flags.">hwloc_type_filter_e</a> for details.</p>
<ul>
<li>
<p class="startli">hwloc_topology_ignore_type(), hwloc_topology_ignore_type_keep_structure() and hwloc_topology_ignore_all_keep_structure() are respectively superseded by </p><pre class="fragment">hwloc_topology_set_type_filter(topology, type, HWLOC_TYPE_FILTER_KEEP_NONE);
hwloc_topology_set_type_filter(topology, type, HWLOC_TYPE_FILTER_KEEP_STRUCTURE);
hwloc_topology_set_all_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_STRUCTURE);
</pre><p class="interli">Also, the meaning of KEEP_STRUCTURE has changed (only entire levels may be ignored, instead of single objects), the old behavior is not available anymore. </p>
<p class="endli"></p>
</li>
<li>
<p class="startli">HWLOC_TOPOLOGY_FLAG_ICACHES is superseded by </p><pre class="fragment">hwloc_topology_set_icache_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_ALL);
</pre> <p class="endli"></p>
</li>
<li>
<p class="startli">HWLOC_TOPOLOGY_FLAG_WHOLE_IO, HWLOC_TOPOLOGY_FLAG_IO_DEVICES and HWLOC_TOPOLOGY_FLAG_IO_BRIDGES replaced.</p>
<p class="interli">To keep all I/O devices (PCI, Bridges, and OS devices), use: </p><pre class="fragment">hwloc_topology_set_io_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_ALL);
</pre><p class="interli">To only keep important devices (Bridges with children, common PCI devices and OS devices): </p><pre class="fragment">hwloc_topology_set_io_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_IMPORTANT);
</pre> <p class="endli"></p>
</li>
</ul>
<h1><a class="anchor" id="upgrade_to_api_2x_xml"></a>
XML changes</h1>
<p>2.0 XML files are not compatible with 1.x</p>
<p>2.0 can load 1.x files, but only NUMA distances are imported. Other distance matrices are ignored (they were never used by default anyway).</p>
<p>2.0 can export 1.x-compatible files, but only distances attached to the root object are exported (i.e. distances that cover the entire machine). Other distance matrices are dropped (they were never used by default anyway).</p>
<p><b>Users are advised to negociate hwloc versions between exporter and importer:</b> If the importer isn't 2.x, the exporter should export to 1.x. Otherwise, things should work by default.</p>
<p>Hence <a class="el" href="a00186.html#ga333f79975b4eeb28a3d8fad3373583ce" title="Export the topology into an XML file.">hwloc_topology_export_xml()</a> and <a class="el" href="a00186.html#gad33b7f7c11db10459505a3b1634fd3f1" title="Export the topology into a newly-allocated XML memory buffer.">hwloc_topology_export_xmlbuffer()</a> have a new flags argument. to force a hwloc-1.x-compatible XML export. </p><ul>
<li>
If both always support 2.0, don't pass any flag. </li>
<li>
When the importer uses hwloc 1.x, export with <a class="el" href="a00186.html#gga0eb99636aff71fe2704e1fa0ffe8c18dae7d6d96546131ef0043867b836b02e0f" title="Export XML that is loadable by hwloc v1.x. However, the export may miss some details about the topolo...">HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1</a>. Otherwise the importer will fail to import. </li>
<li>
When the exporter uses hwloc 1.x, it cannot pass any flag, and a 2.0 importer can import without problem. </li>
</ul>
<pre class="fragment">#if HWLOC_API_VERSION >= 0x20000
if (need 1.x compatible XML export)
hwloc_topology_export_xml(...., HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1);
else /* need 2.x compatible XML export */
hwloc_topology_export_xml(...., 0);
#else
hwloc_topology_export_xml(....);
#endif
</pre><p>Additionally, <a class="el" href="a00208.html#ga2cd902ce8766e90d4f2523a8e87640e9" title="Load a list of topology differences from a XML file.">hwloc_topology_diff_load_xml()</a>, <a class="el" href="a00208.html#gad693810a5c51628529b9dd56f040fb81" title="Load a list of topology differences from a XML buffer.">hwloc_topology_diff_load_xmlbuffer()</a>, <a class="el" href="a00208.html#ga8a14dd7d01efbdd97af7fe85e8b84b20" title="Export a list of topology differences to a XML file.">hwloc_topology_diff_export_xml()</a>, <a class="el" href="a00208.html#gaa2f0918df60c1c4a0bef9411f7d92a13" title="Export a list of topology differences to a XML buffer.">hwloc_topology_diff_export_xmlbuffer()</a> and <a class="el" href="a00208.html#ga5dcff18f80583ac6505a94ba2877fd1b" title="Destroy a list of topology differences.">hwloc_topology_diff_destroy()</a> lost the topology argument: The first argument (topology) isn't needed anymore.</p>
<h1><a class="anchor" id="upgrade_to_api_2x_distances"></a>
Distances API totally rewritten</h1>
<p>The new distances API is in <a class="el" href="a00107_source.html">hwloc/distances.h</a>.</p>
<p>Distances are not accessible directly from objects anymore. One should first call <a class="el" href="a00188.html#ga613e6b2a5d0f06626ee8d0c12fa46691" title="Retrieve distance matrices.">hwloc_distances_get()</a> (or a variant) to retrieve distances (possibly with one call to get the number of available distances structures, and another call to actually get them). Then it may consult these structures, and finally release them.</p>
<p>The set of object involved in a distances structure is specified by an array of objects, it may not always cover the entire machine or so.</p>
<h1><a class="anchor" id="upgrade_to_api_2x_return"></a>
Return values of functions</h1>
<p>Bitmap functions (and a couple other functions) can return errors (in theory).</p>
<p>Most bitmap functions may have to reallocate the internal bitmap storage. In v1.x, they would silently crash if realloc failed. In v2.0, they now return an int that can be negative on error. However, the preallocated storage is 512 bits, hence realloc will not even be used unless you run hwloc on machines with larger PU or NUMAnode indexes.</p>
<p><a class="el" href="a00169.html#gace7654bb8a9002caae1a4b8a59e7452e" title="Add the given name and value pair to the given object info attributes.">hwloc_obj_add_info()</a>, <a class="el" href="a00183.html#gae8180d79a731d610836f2a4789e00db1" title="Convert a NUMA node set into a CPU set.">hwloc_cpuset_from_nodeset()</a> and <a class="el" href="a00183.html#gae8180d79a731d610836f2a4789e00db1" title="Convert a NUMA node set into a CPU set.">hwloc_cpuset_from_nodeset()</a> also return an int, which would be -1 in case of allocation errors.</p>
<h1><a class="anchor" id="upgrade_to_api_2x_misc"></a>
Misc API changes</h1>
<ul>
<li>
<p class="startli"><a class="el" href="a00168.html#ga510f21b066fba2dab12b8c9b173b1dfd" title="Return an object type and attributes from a type string.">hwloc_type_sscanf()</a> extends hwloc_obj_type_sscanf() by passing a union <a class="el" href="a00224.html" title="Object type-specific Attributes.">hwloc_obj_attr_u</a> which may receive Cache, Group, Bridge or OS device attributes. </p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><a class="el" href="a00168.html#ga52c63cd7203e55b804c1314affc9bd12" title="Return an object type and its level depth from a type string.">hwloc_type_sscanf_as_depth()</a> is also added to directly return the corresponding level depth within a topology. </p>
<p class="endli"></p>
</li>
<li>
<p class="startli">hwloc_topology_insert_misc_object_by_cpuset() is replaced with <a class="el" href="a00174.html#ga4cea4741165faf5323931a9ed8786ef7" title="Allocate a Group object to insert later with hwloc_topology_insert_group_object().">hwloc_topology_alloc_group_object()</a> and <a class="el" href="a00174.html#ga1fc6012b3e1c249b83f48cb7bcacaa5b" title="Add more structure to the topology by adding an intermediate Group.">hwloc_topology_insert_group_object()</a>. </p>
<p class="endli"></p>
</li>
<li>
<p class="startli">hwloc_topology_insert_misc_object_by_parent() is replaced with <a class="el" href="a00174.html#gad980782ade737900c5cf208946768c30" title="Add a MISC object as a leaf of the topology.">hwloc_topology_insert_misc_object()</a>. </p>
<p class="endli"></p>
</li>
</ul>
<h1><a class="anchor" id="upgrade_to_api_2x_removals"></a>
API removals and deprecations</h1>
<ul>
<li>
<p class="startli">HWLOC_OBJ_SYSTEM removed: The root object is always <a class="el" href="a00164.html#ggacd37bb612667dc437d66bfb175a8dc55a3f4e83ffc4a259354959ae8a9eaa2a80" title="Machine. A set of processors and memory with cache coherency.">HWLOC_OBJ_MACHINE</a> </p>
<p class="endli"></p>
</li>
<li>
<p class="startli">_membind_nodeset() memory binding interfaces deprecated: One should use the variant without _nodeset suffix and pass the <a class="el" href="a00171.html#ggab00475fd98815bf4fb9aaf752030e7d2a71f19fe4505f1c083dc8e6f7bdea6256" title="Consider the bitmap argument as a nodeset.">HWLOC_MEMBIND_BYNODESET</a> flag. </p>
<p class="endli"></p>
</li>
<li>
<p class="startli">HWLOC_MEMBIND_REPLICATE removed: no supported operating system supports it anymore. </p>
<p class="endli"></p>
</li>
<li>
<p class="startli">hwloc_obj_snprintf() removed because it was long-deprecated by <a class="el" href="a00168.html#gadb8765c260edea80c52cd06a76639ba4" title="Stringify the type of a given topology object into a human-readable form.">hwloc_obj_type_snprintf()</a> and <a class="el" href="a00168.html#ga870e876931c282a1c7aee2f031912ce3" title="Stringify the attributes of a given topology object into a human-readable form.">hwloc_obj_attr_snprintf()</a>. </p>
<p class="endli"></p>
</li>
<li>
<p class="startli">hwloc_obj_type_sscanf() deprecated, hwloc_obj_type_of_string() removed. </p>
<p class="endli"></p>
</li>
<li>
<p class="startli">hwloc_cpuset_from/to_nodeset_strict() deprecated: Now useless since all topologies are NUMA. Use the variant without the _strict suffix </p>
<p class="endli"></p>
</li>
<li>
<p class="startli">hwloc_distribute() and hwloc_distributev() removed, deprecated by <a class="el" href="a00181.html#gac14e61485402837e87293079fa0270f2" title="Distribute n items over the topology under roots.">hwloc_distrib()</a>. </p>
<p class="endli"></p>
</li>
<li>
<p class="startli">The Custom interface (hwloc_topology_set_custom(), etc.) was removed, as well as the corresponding command-line tools (hwloc-assembler, etc.). Topologies always start with object with valid cpusets and nodesets. </p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>obj->online_cpuset</code> removed: Offline PUs are simply listed in the <code>complete_cpuset</code> as previously. </p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>obj->os_level</code> removed. </p>
<p class="endli"></p>
</li>
</ul>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- 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>
|
