| 1 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| 2 |
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US"> |
| 3 |
<head> |
| 4 |
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> |
| 5 |
<meta http-equiv="X-UA-Compatible" content="IE=11"/> |
| 6 |
<meta name="generator" content="Doxygen 1.15.0"/> |
| 7 |
<meta name="viewport" content="width=device-width, initial-scale=1"/> |
| 8 |
<title>Hardware Locality (hwloc): Kinds of CPU cores</title> |
| 9 |
<link href="tabs.css" rel="stylesheet" type="text/css"/> |
| 10 |
<script type="text/javascript" src="jquery.js"></script> |
| 11 |
<script type="text/javascript" src="dynsections.js"></script> |
| 12 |
<script type="text/javascript" src="clipboard.js"></script> |
| 13 |
<link href="doxygen.css" rel="stylesheet" type="text/css" /> |
| 14 |
</head> |
| 15 |
<body> |
| 16 |
<div id="top"><!-- do not remove this div, it is closed by doxygen! --> |
| 17 |
<div id="titlearea"> |
| 18 |
<table cellspacing="0" cellpadding="0"> |
| 19 |
<tbody> |
| 20 |
<tr id="projectrow"> |
| 21 |
<td id="projectalign"> |
| 22 |
<div id="projectname">Hardware Locality (hwloc)<span id="projectnumber"> 2.14.0</span> |
| 23 |
</div> |
| 24 |
</td> |
| 25 |
</tr> |
| 26 |
</tbody> |
| 27 |
</table> |
| 28 |
</div> |
| 29 |
<!-- end header part --> |
| 30 |
<!-- Generated by Doxygen 1.15.0 --> |
| 31 |
<script type="text/javascript"> |
| 32 |
$(function() { codefold.init(); }); |
| 33 |
</script> |
| 34 |
<script type="text/javascript" src="menudata.js"></script> |
| 35 |
<script type="text/javascript" src="menu.js"></script> |
| 36 |
<script type="text/javascript"> |
| 37 |
$(function() { |
| 38 |
initMenu('',false,false,'search.php','Search',false); |
| 39 |
}); |
| 40 |
</script> |
| 41 |
<div id="main-nav"></div> |
| 42 |
</div><!-- top --> |
| 43 |
<div id="doc-content"> |
| 44 |
<div class="header"> |
| 45 |
<div class="summary"> |
| 46 |
<a href="#func-members">Functions</a> </div> |
| 47 |
<div class="headertitle"><div class="title">Kinds of CPU cores </div></div> |
| 48 |
</div><!--header--> |
| 49 |
<div class="contents"> |
| 50 |
<table class="memberdecls"> |
| 51 |
<tr class="heading"><td colspan="2"><h2 id="header-func-members" class="groupheader"><a id="func-members" name="func-members"></a> |
| 52 |
Functions</h2></td></tr> |
| 53 |
<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="#ga7553f7c6d3920b169f3fc18dfe6a33e3">hwloc_cpukinds_get_nr</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, unsigned long flags)</td></tr> |
| 54 |
<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="#gaf979833aab18d2e7f4b17c932cbcf5d8">hwloc_cpukinds_get_by_cpuset</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, <a class="el" href="a00188.html#gae991a108af01d408be2776c5b2c467b2">hwloc_const_bitmap_t</a> cpuset, unsigned long flags)</td></tr> |
| 55 |
<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="#gae1b38fbe9c645583fc16052ce6fbb275">hwloc_cpukinds_get_info</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, unsigned kind_index, <a class="el" href="a00188.html#gaa3c2bf4c776d603dcebbb61b0c923d84">hwloc_bitmap_t</a> cpuset, int *efficiency, unsigned *nr_infos, struct <a class="el" href="a00272.html">hwloc_info_s</a> **infos, unsigned long flags)</td></tr> |
| 56 |
<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="#ga6164ba92cfd06f530ec2c4a18a0dd5a9">hwloc_cpukinds_register</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, <a class="el" href="a00188.html#gaa3c2bf4c776d603dcebbb61b0c923d84">hwloc_bitmap_t</a> cpuset, int forced_efficiency, unsigned nr_infos, struct <a class="el" href="a00272.html">hwloc_info_s</a> *infos, unsigned long flags)</td></tr> |
| 57 |
</table> |
| 58 |
<a name="details" id="details"></a><h2 id="header-details" class="groupheader">Detailed Description</h2> |
| 59 |
<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> |
| 60 |
<p>The number of kinds may be obtained with <a class="el" href="#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> |
| 61 |
<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="#gaf979833aab18d2e7f4b17c932cbcf5d8" title="Get the index of the CPU kind that contains CPUs listed in cpuset.">hwloc_cpukinds_get_by_cpuset()</a>.</p> |
| 62 |
<p>From the index of a kind, it is possible to retrieve information with <a class="el" href="#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="a00378.html#topoattrs_cpukinds">CPU Kinds</a>).</p> |
| 63 |
<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 class="param">kind_index</code> to <a class="el" href="#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 class="param">kind_index</code> values would rather return information about power-hungry high-performance cores.</p> |
| 64 |
<p>When available, efficiency values are gathered from the operating system. If so, <code class="param">cpukind_efficiency</code> is set in the struct <a class="el" href="a00276.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> |
| 65 |
<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="a00373.html#envvar_heuristics">Environment variables for tweaking hwloc heuristics</a>.</p> |
| 66 |
<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> |
| 67 |
<a name="doc-func-members" id="doc-func-members"></a><h2 id="header-doc-func-members" class="groupheader">Function Documentation</h2> |
| 68 |
<a id="gaf979833aab18d2e7f4b17c932cbcf5d8" name="gaf979833aab18d2e7f4b17c932cbcf5d8"></a> |
| 69 |
<h2 class="memtitle"><span class="permalink"><a href="#gaf979833aab18d2e7f4b17c932cbcf5d8">◆ </a></span>hwloc_cpukinds_get_by_cpuset()</h2> |
| 70 |
|
| 71 |
<div class="memitem"> |
| 72 |
<div class="memproto"> |
| 73 |
<table class="memname"> |
| 74 |
<tr> |
| 75 |
<td class="memname">int hwloc_cpukinds_get_by_cpuset </td> |
| 76 |
<td>(</td> |
| 77 |
<td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td> |
| 78 |
</tr> |
| 79 |
<tr> |
| 80 |
<td class="paramkey"></td> |
| 81 |
<td></td> |
| 82 |
<td class="paramtype"><a class="el" href="a00188.html#gae991a108af01d408be2776c5b2c467b2">hwloc_const_bitmap_t</a></td> <td class="paramname"><span class="paramname"><em>cpuset</em></span>, </td> |
| 83 |
</tr> |
| 84 |
<tr> |
| 85 |
<td class="paramkey"></td> |
| 86 |
<td></td> |
| 87 |
<td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>flags</em></span> )</td> |
| 88 |
</tr> |
| 89 |
</table> |
| 90 |
</div><div class="memdoc"> |
| 91 |
|
| 92 |
<p>Get the index of the CPU kind that contains CPUs listed in <code class="param">cpuset</code>. </p> |
| 93 |
<p><code class="param">flags</code> must be <code>0</code> for now.</p> |
| 94 |
<dl class="section return"><dt>Returns</dt><dd>The index of the CPU kind (positive integer or 0) on success. </dd> |
| 95 |
<dd> |
| 96 |
<code>-1</code> with <code class="param">errno</code> set to <code>EXDEV</code> if <code class="param">cpuset</code> is only partially included in the some kind. </dd> |
| 97 |
<dd> |
| 98 |
<code>-1</code> with <code class="param">errno</code> set to <code>ENOENT</code> if <code class="param">cpuset</code> is not included in any kind, even partially. </dd> |
| 99 |
<dd> |
| 100 |
<code>-1</code> with <code class="param">errno</code> set to <code>EINVAL</code> if parameters are invalid. </dd></dl> |
| 101 |
|
| 102 |
</div> |
| 103 |
</div> |
| 104 |
<a id="gae1b38fbe9c645583fc16052ce6fbb275" name="gae1b38fbe9c645583fc16052ce6fbb275"></a> |
| 105 |
<h2 class="memtitle"><span class="permalink"><a href="#gae1b38fbe9c645583fc16052ce6fbb275">◆ </a></span>hwloc_cpukinds_get_info()</h2> |
| 106 |
|
| 107 |
<div class="memitem"> |
| 108 |
<div class="memproto"> |
| 109 |
<table class="memname"> |
| 110 |
<tr> |
| 111 |
<td class="memname">int hwloc_cpukinds_get_info </td> |
| 112 |
<td>(</td> |
| 113 |
<td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td> |
| 114 |
</tr> |
| 115 |
<tr> |
| 116 |
<td class="paramkey"></td> |
| 117 |
<td></td> |
| 118 |
<td class="paramtype">unsigned</td> <td class="paramname"><span class="paramname"><em>kind_index</em></span>, </td> |
| 119 |
</tr> |
| 120 |
<tr> |
| 121 |
<td class="paramkey"></td> |
| 122 |
<td></td> |
| 123 |
<td class="paramtype"><a class="el" href="a00188.html#gaa3c2bf4c776d603dcebbb61b0c923d84">hwloc_bitmap_t</a></td> <td class="paramname"><span class="paramname"><em>cpuset</em></span>, </td> |
| 124 |
</tr> |
| 125 |
<tr> |
| 126 |
<td class="paramkey"></td> |
| 127 |
<td></td> |
| 128 |
<td class="paramtype">int *</td> <td class="paramname"><span class="paramname"><em>efficiency</em></span>, </td> |
| 129 |
</tr> |
| 130 |
<tr> |
| 131 |
<td class="paramkey"></td> |
| 132 |
<td></td> |
| 133 |
<td class="paramtype">unsigned *</td> <td class="paramname"><span class="paramname"><em>nr_infos</em></span>, </td> |
| 134 |
</tr> |
| 135 |
<tr> |
| 136 |
<td class="paramkey"></td> |
| 137 |
<td></td> |
| 138 |
<td class="paramtype">struct <a class="el" href="a00272.html">hwloc_info_s</a> **</td> <td class="paramname"><span class="paramname"><em>infos</em></span>, </td> |
| 139 |
</tr> |
| 140 |
<tr> |
| 141 |
<td class="paramkey"></td> |
| 142 |
<td></td> |
| 143 |
<td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>flags</em></span> )</td> |
| 144 |
</tr> |
| 145 |
</table> |
| 146 |
</div><div class="memdoc"> |
| 147 |
|
| 148 |
<p>Get the CPU set and infos about a CPU kind in the topology. </p> |
| 149 |
<p><code class="param">kind_index</code> identifies one kind of CPU between 0 and the number of kinds returned by <a class="el" href="#ga7553f7c6d3920b169f3fc18dfe6a33e3" title="Get the number of different kinds of CPU cores in the topology.">hwloc_cpukinds_get_nr()</a> minus 1.</p> |
| 150 |
<p>If not <code>NULL</code>, the bitmap <code class="param">cpuset</code> will be filled with the set of PUs of this kind.</p> |
| 151 |
<p>The integer pointed by <code class="param">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="#ga7553f7c6d3920b169f3fc18dfe6a33e3" title="Get the number of different kinds of CPU cores in the topology.">hwloc_cpukinds_get_nr()</a>) minus 1.</p> |
| 152 |
<p>Kinds with lower efficiency are reported first.</p> |
| 153 |
<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> |
| 154 |
<p>The array of info attributes (for instance the "CoreType", "FrequencyMaxMHz" or "FrequencyBaseMHz", see <a class="el" href="a00378.html#topoattrs_cpukinds">CPU Kinds</a>) and its length are returned in <code class="param">infos</code> or <code class="param">nr_infos</code>. The array belongs to the topology, it should not be freed or modified.</p> |
| 155 |
<p>If <code class="param">nr_infos</code> or <code class="param">infos</code> is <code>NULL</code>, no info is returned.</p> |
| 156 |
<p><code class="param">flags</code> must be <code>0</code> for now.</p> |
| 157 |
<dl class="section return"><dt>Returns</dt><dd><code>0</code> on success. </dd> |
| 158 |
<dd> |
| 159 |
<code>-1</code> with <code class="param">errno</code> set to <code>ENOENT</code> if <code class="param">kind_index</code> does not match any CPU kind. </dd> |
| 160 |
<dd> |
| 161 |
<code>-1</code> with <code class="param">errno</code> set to <code>EINVAL</code> if parameters are invalid. </dd></dl> |
| 162 |
|
| 163 |
</div> |
| 164 |
</div> |
| 165 |
<a id="ga7553f7c6d3920b169f3fc18dfe6a33e3" name="ga7553f7c6d3920b169f3fc18dfe6a33e3"></a> |
| 166 |
<h2 class="memtitle"><span class="permalink"><a href="#ga7553f7c6d3920b169f3fc18dfe6a33e3">◆ </a></span>hwloc_cpukinds_get_nr()</h2> |
| 167 |
|
| 168 |
<div class="memitem"> |
| 169 |
<div class="memproto"> |
| 170 |
<table class="memname"> |
| 171 |
<tr> |
| 172 |
<td class="memname">int hwloc_cpukinds_get_nr </td> |
| 173 |
<td>(</td> |
| 174 |
<td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td> |
| 175 |
</tr> |
| 176 |
<tr> |
| 177 |
<td class="paramkey"></td> |
| 178 |
<td></td> |
| 179 |
<td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>flags</em></span> )</td> |
| 180 |
</tr> |
| 181 |
</table> |
| 182 |
</div><div class="memdoc"> |
| 183 |
|
| 184 |
<p>Get the number of different kinds of CPU cores in the topology. </p> |
| 185 |
<p><code class="param">flags</code> must be <code>0</code> for now.</p> |
| 186 |
<dl class="section return"><dt>Returns</dt><dd>The number of CPU kinds (positive integer) on success. </dd> |
| 187 |
<dd> |
| 188 |
<code>0</code> if no information about kinds was found. </dd> |
| 189 |
<dd> |
| 190 |
<code>-1</code> with <code class="param">errno</code> set to <code>EINVAL</code> if <code class="param">flags</code> is invalid. </dd></dl> |
| 191 |
|
| 192 |
</div> |
| 193 |
</div> |
| 194 |
<a id="ga6164ba92cfd06f530ec2c4a18a0dd5a9" name="ga6164ba92cfd06f530ec2c4a18a0dd5a9"></a> |
| 195 |
<h2 class="memtitle"><span class="permalink"><a href="#ga6164ba92cfd06f530ec2c4a18a0dd5a9">◆ </a></span>hwloc_cpukinds_register()</h2> |
| 196 |
|
| 197 |
<div class="memitem"> |
| 198 |
<div class="memproto"> |
| 199 |
<table class="memname"> |
| 200 |
<tr> |
| 201 |
<td class="memname">int hwloc_cpukinds_register </td> |
| 202 |
<td>(</td> |
| 203 |
<td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td> |
| 204 |
</tr> |
| 205 |
<tr> |
| 206 |
<td class="paramkey"></td> |
| 207 |
<td></td> |
| 208 |
<td class="paramtype"><a class="el" href="a00188.html#gaa3c2bf4c776d603dcebbb61b0c923d84">hwloc_bitmap_t</a></td> <td class="paramname"><span class="paramname"><em>cpuset</em></span>, </td> |
| 209 |
</tr> |
| 210 |
<tr> |
| 211 |
<td class="paramkey"></td> |
| 212 |
<td></td> |
| 213 |
<td class="paramtype">int</td> <td class="paramname"><span class="paramname"><em>forced_efficiency</em></span>, </td> |
| 214 |
</tr> |
| 215 |
<tr> |
| 216 |
<td class="paramkey"></td> |
| 217 |
<td></td> |
| 218 |
<td class="paramtype">unsigned</td> <td class="paramname"><span class="paramname"><em>nr_infos</em></span>, </td> |
| 219 |
</tr> |
| 220 |
<tr> |
| 221 |
<td class="paramkey"></td> |
| 222 |
<td></td> |
| 223 |
<td class="paramtype">struct <a class="el" href="a00272.html">hwloc_info_s</a> *</td> <td class="paramname"><span class="paramname"><em>infos</em></span>, </td> |
| 224 |
</tr> |
| 225 |
<tr> |
| 226 |
<td class="paramkey"></td> |
| 227 |
<td></td> |
| 228 |
<td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>flags</em></span> )</td> |
| 229 |
</tr> |
| 230 |
</table> |
| 231 |
</div><div class="memdoc"> |
| 232 |
|
| 233 |
<p>Register a kind of CPU in the topology. </p> |
| 234 |
<p>Mark the PUs listed in <code class="param">cpuset</code> as being of the same kind with respect to the given attributes.</p> |
| 235 |
<p><code class="param">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> |
| 236 |
<p>The array <code class="param">infos</code> of size <code class="param">nr_infos</code> may be used to provide info names and values describing this kind of PUs.</p> |
| 237 |
<p><code class="param">flags</code> must be <code>0</code> for now.</p> |
| 238 |
<p>Parameters <code class="param">cpuset</code> and <code class="param">infos</code> will be duplicated internally, the caller is responsible for freeing them.</p> |
| 239 |
<p>If <code class="param">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> |
| 240 |
<dl class="section note"><dt>Note</dt><dd>The efficiency <code class="param">forced_efficiency</code> provided to this function may be different from the one reported later by <a class="el" href="#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> |
| 241 |
<dl class="section return"><dt>Returns</dt><dd><code>0</code> on success. </dd> |
| 242 |
<dd> |
| 243 |
<code>-1</code> with <code class="param">errno</code> set to <code>EINVAL</code> if some parameters are invalid, for instance if <code class="param">cpuset</code> is <code>NULL</code> or empty. </dd></dl> |
| 244 |
|
| 245 |
</div> |
| 246 |
</div> |
| 247 |
</div><!-- contents --> |
| 248 |
<!-- start footer part --> |
| 249 |
<hr class="footer"/><address class="footer"><small> |
| 250 |
Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.15.0 |
| 251 |
</small></address> |
| 252 |
</div><!-- doc-content --> |
| 253 |
</body> |
| 254 |
</html> |