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
|
<!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): Kinds of CPU cores</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 class="header">
<div class="summary">
<a href="#func-members">Functions</a> </div>
<div class="headertitle"><div class="title">Kinds of CPU cores</div></div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="func-members" name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga7553f7c6d3920b169f3fc18dfe6a33e3" id="r_ga7553f7c6d3920b169f3fc18dfe6a33e3"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="a00194.html#ga7553f7c6d3920b169f3fc18dfe6a33e3">hwloc_cpukinds_get_nr</a> (<a class="el" href="a00166.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, unsigned long flags)</td></tr>
<tr class="separator:ga7553f7c6d3920b169f3fc18dfe6a33e3"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gaf979833aab18d2e7f4b17c932cbcf5d8" id="r_gaf979833aab18d2e7f4b17c932cbcf5d8"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="a00194.html#gaf979833aab18d2e7f4b17c932cbcf5d8">hwloc_cpukinds_get_by_cpuset</a> (<a class="el" href="a00166.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, <a class="el" href="a00185.html#gae991a108af01d408be2776c5b2c467b2">hwloc_const_bitmap_t</a> cpuset, unsigned long flags)</td></tr>
<tr class="separator:gaf979833aab18d2e7f4b17c932cbcf5d8"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gae1b38fbe9c645583fc16052ce6fbb275" id="r_gae1b38fbe9c645583fc16052ce6fbb275"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="a00194.html#gae1b38fbe9c645583fc16052ce6fbb275">hwloc_cpukinds_get_info</a> (<a class="el" href="a00166.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, unsigned kind_index, <a class="el" href="a00185.html#gaa3c2bf4c776d603dcebbb61b0c923d84">hwloc_bitmap_t</a> cpuset, int *efficiency, unsigned *nr_infos, struct <a class="el" href="a00268.html">hwloc_info_s</a> **infos, unsigned long flags)</td></tr>
<tr class="separator:gae1b38fbe9c645583fc16052ce6fbb275"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga6164ba92cfd06f530ec2c4a18a0dd5a9" id="r_ga6164ba92cfd06f530ec2c4a18a0dd5a9"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="a00194.html#ga6164ba92cfd06f530ec2c4a18a0dd5a9">hwloc_cpukinds_register</a> (<a class="el" href="a00166.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, <a class="el" href="a00185.html#gaa3c2bf4c776d603dcebbb61b0c923d84">hwloc_bitmap_t</a> cpuset, int forced_efficiency, unsigned nr_infos, struct <a class="el" href="a00268.html">hwloc_info_s</a> *infos, unsigned long flags)</td></tr>
<tr class="separator:ga6164ba92cfd06f530ec2c4a18a0dd5a9"><td class="memSeparator" colspan="2"> </td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>Platforms with heterogeneous CPUs may have some cores with different features or frequencies. This API exposes identical PUs in sets called CPU kinds. Each PU of the topology may only be in a single kind.</p>
<p>The number of kinds may be obtained with <a class="el" href="a00194.html#ga7553f7c6d3920b169f3fc18dfe6a33e3" title="Get the number of different kinds of CPU cores in the topology.">hwloc_cpukinds_get_nr()</a>. If the platform is homogeneous, there may be a single kind with all PUs. If the platform or operating system does not expose any information about CPU cores, there may be no kind at all.</p>
<p>The index of the kind that describes a given CPU set (if any, and not partially) may be obtained with <a class="el" href="a00194.html#gaf979833aab18d2e7f4b17c932cbcf5d8" title="Get the index of the CPU kind that contains CPUs listed in cpuset.">hwloc_cpukinds_get_by_cpuset()</a>.</p>
<p>From the index of a kind, it is possible to retrieve information with <a class="el" href="a00194.html#gae1b38fbe9c645583fc16052ce6fbb275" title="Get the CPU set and infos about a CPU kind in the topology.">hwloc_cpukinds_get_info()</a>: an abstracted efficiency value, and an array of info attributes (for instance the "CoreType" and "FrequencyMaxMHz", see <a class="el" href="a00374.html#topoattrs_cpukinds">CPU Kinds</a>).</p>
<p>A higher efficiency value means greater intrinsic performance (and possibly less performance/power efficiency). Kinds with lower efficiency values are ranked first: Passing 0 as <code>kind_index</code> to <a class="el" href="a00194.html#gae1b38fbe9c645583fc16052ce6fbb275" title="Get the CPU set and infos about a CPU kind in the topology.">hwloc_cpukinds_get_info()</a> will return information about the CPU kind with lower performance but higher energy-efficiency. Higher <code>kind_index</code> values would rather return information about power-hungry high-performance cores.</p>
<p>When available, efficiency values are gathered from the operating system. If so, <code>cpukind_efficiency</code> is set in the struct <a class="el" href="a00272.html" title="Flags describing actual discovery support for this topology.">hwloc_topology_discovery_support</a> array. This is currently available on Windows 10, Mac OS X (Darwin), and on some Linux platforms where core "capacity" is exposed in sysfs.</p>
<p>If the operating system does not expose core efficiencies natively, hwloc tries to compute efficiencies by comparing CPU kinds using frequencies (on ARM), or core types and frequencies (on other architectures). The environment variable HWLOC_CPUKINDS_RANKING may be used to change this heuristics, see <a class="el" href="a00369.html">Environment Variables</a>.</p>
<p>If hwloc fails to rank any kind, for instance because the operating system does not expose efficiencies and core frequencies, all kinds will have an unknown efficiency (<code>-1</code>), and they are not indexed/ordered in any specific way. </p>
<h2 class="groupheader">Function Documentation</h2>
<a id="gaf979833aab18d2e7f4b17c932cbcf5d8" name="gaf979833aab18d2e7f4b17c932cbcf5d8"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gaf979833aab18d2e7f4b17c932cbcf5d8">◆ </a></span>hwloc_cpukinds_get_by_cpuset()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int hwloc_cpukinds_get_by_cpuset </td>
<td>(</td>
<td class="paramtype"><a class="el" href="a00166.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> </td>
<td class="paramname"><em>topology</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="a00185.html#gae991a108af01d408be2776c5b2c467b2">hwloc_const_bitmap_t</a> </td>
<td class="paramname"><em>cpuset</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned long </td>
<td class="paramname"><em>flags</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Get the index of the CPU kind that contains CPUs listed in <code>cpuset</code>. </p>
<p><code>flags</code> must be <code>0</code> for now.</p>
<dl class="section return"><dt>Returns</dt><dd>The index of the CPU kind (positive integer or 0) on success. </dd>
<dd>
<code>-1</code> with <code>errno</code> set to <code>EXDEV</code> if <code>cpuset</code> is only partially included in the some kind. </dd>
<dd>
<code>-1</code> with <code>errno</code> set to <code>ENOENT</code> if <code>cpuset</code> is not included in any kind, even partially. </dd>
<dd>
<code>-1</code> with <code>errno</code> set to <code>EINVAL</code> if parameters are invalid. </dd></dl>
</div>
</div>
<a id="gae1b38fbe9c645583fc16052ce6fbb275" name="gae1b38fbe9c645583fc16052ce6fbb275"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gae1b38fbe9c645583fc16052ce6fbb275">◆ </a></span>hwloc_cpukinds_get_info()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int hwloc_cpukinds_get_info </td>
<td>(</td>
<td class="paramtype"><a class="el" href="a00166.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> </td>
<td class="paramname"><em>topology</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned </td>
<td class="paramname"><em>kind_index</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="a00185.html#gaa3c2bf4c776d603dcebbb61b0c923d84">hwloc_bitmap_t</a> </td>
<td class="paramname"><em>cpuset</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>efficiency</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned * </td>
<td class="paramname"><em>nr_infos</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct <a class="el" href="a00268.html">hwloc_info_s</a> ** </td>
<td class="paramname"><em>infos</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned long </td>
<td class="paramname"><em>flags</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Get the CPU set and infos about a CPU kind in the topology. </p>
<p><code>kind_index</code> identifies one kind of CPU between 0 and the number of kinds returned by <a class="el" href="a00194.html#ga7553f7c6d3920b169f3fc18dfe6a33e3" title="Get the number of different kinds of CPU cores in the topology.">hwloc_cpukinds_get_nr()</a> minus 1.</p>
<p>If not <code>NULL</code>, the bitmap <code>cpuset</code> will be filled with the set of PUs of this kind.</p>
<p>The integer pointed by <code>efficiency</code>, if not <code>NULL</code> will, be filled with the ranking of this kind of CPU in term of efficiency (see above). It ranges from <code>0</code> to the number of kinds (as reported by <a class="el" href="a00194.html#ga7553f7c6d3920b169f3fc18dfe6a33e3" title="Get the number of different kinds of CPU cores in the topology.">hwloc_cpukinds_get_nr()</a>) minus 1.</p>
<p>Kinds with lower efficiency are reported first.</p>
<p>If there is a single kind in the topology, its efficiency <code>0</code>. If the efficiency of some kinds of cores is unknown, the efficiency of all kinds is set to <code>-1</code>, and kinds are reported in no specific order.</p>
<p>The array of info attributes (for instance the "CoreType", "FrequencyMaxMHz" or "FrequencyBaseMHz", see <a class="el" href="a00374.html#topoattrs_cpukinds">CPU Kinds</a>) and its length are returned in <code>infos</code> or <code>nr_infos</code>. The array belongs to the topology, it should not be freed or modified.</p>
<p>If <code>nr_infos</code> or <code>infos</code> is <code>NULL</code>, no info is returned.</p>
<p><code>flags</code> must be <code>0</code> for now.</p>
<dl class="section return"><dt>Returns</dt><dd><code>0</code> on success. </dd>
<dd>
<code>-1</code> with <code>errno</code> set to <code>ENOENT</code> if <code>kind_index</code> does not match any CPU kind. </dd>
<dd>
<code>-1</code> with <code>errno</code> set to <code>EINVAL</code> if parameters are invalid. </dd></dl>
</div>
</div>
<a id="ga7553f7c6d3920b169f3fc18dfe6a33e3" name="ga7553f7c6d3920b169f3fc18dfe6a33e3"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga7553f7c6d3920b169f3fc18dfe6a33e3">◆ </a></span>hwloc_cpukinds_get_nr()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int hwloc_cpukinds_get_nr </td>
<td>(</td>
<td class="paramtype"><a class="el" href="a00166.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> </td>
<td class="paramname"><em>topology</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned long </td>
<td class="paramname"><em>flags</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Get the number of different kinds of CPU cores in the topology. </p>
<p><code>flags</code> must be <code>0</code> for now.</p>
<dl class="section return"><dt>Returns</dt><dd>The number of CPU kinds (positive integer) on success. </dd>
<dd>
<code>0</code> if no information about kinds was found. </dd>
<dd>
<code>-1</code> with <code>errno</code> set to <code>EINVAL</code> if <code>flags</code> is invalid. </dd></dl>
</div>
</div>
<a id="ga6164ba92cfd06f530ec2c4a18a0dd5a9" name="ga6164ba92cfd06f530ec2c4a18a0dd5a9"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga6164ba92cfd06f530ec2c4a18a0dd5a9">◆ </a></span>hwloc_cpukinds_register()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int hwloc_cpukinds_register </td>
<td>(</td>
<td class="paramtype"><a class="el" href="a00166.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> </td>
<td class="paramname"><em>topology</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="a00185.html#gaa3c2bf4c776d603dcebbb61b0c923d84">hwloc_bitmap_t</a> </td>
<td class="paramname"><em>cpuset</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>forced_efficiency</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned </td>
<td class="paramname"><em>nr_infos</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct <a class="el" href="a00268.html">hwloc_info_s</a> * </td>
<td class="paramname"><em>infos</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned long </td>
<td class="paramname"><em>flags</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Register a kind of CPU in the topology. </p>
<p>Mark the PUs listed in <code>cpuset</code> as being of the same kind with respect to the given attributes.</p>
<p><code>forced_efficiency</code> should be <code>-1</code> if unknown. Otherwise it is an abstracted efficiency value to enforce the ranking of all kinds if all of them have valid (and different) efficiencies.</p>
<p>The array <code>infos</code> of size <code>nr_infos</code> may be used to provide info names and values describing this kind of PUs.</p>
<p><code>flags</code> must be <code>0</code> for now.</p>
<p>Parameters <code>cpuset</code> and <code>infos</code> will be duplicated internally, the caller is responsible for freeing them.</p>
<p>If <code>cpuset</code> overlaps with some existing kinds, those might get modified or split. For instance if existing kind A contains PUs 0 and 1, and one registers another kind for PU 1 and 2, there will be 3 resulting kinds: existing kind A is restricted to only PU 0; new kind B contains only PU 1 and combines information from A and from the newly-registered kind; new kind C contains only PU 2 and only gets information from the newly-registered kind.</p>
<dl class="section note"><dt>Note</dt><dd>The efficiency <code>forced_efficiency</code> provided to this function may be different from the one reported later by <a class="el" href="a00194.html#gae1b38fbe9c645583fc16052ce6fbb275" title="Get the CPU set and infos about a CPU kind in the topology.">hwloc_cpukinds_get_info()</a> because hwloc will scale efficiency values down to between 0 and the number of kinds minus 1.</dd></dl>
<dl class="section return"><dt>Returns</dt><dd><code>0</code> on success. </dd>
<dd>
<code>-1</code> with <code>errno</code> set to <code>EINVAL</code> if some parameters are invalid, for instance if <code>cpuset</code> is <code>NULL</code> or empty. </dd></dl>
</div>
</div>
</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>
|
