Debian Codegraph @

doc/doxygen-doc/man/man3/hwlocality_cpukinds.3

raw
1 .TH "hwlocality_cpukinds" 3 "Version 2.14.0" "Hardware Locality (hwloc)" \" -*- nroff -*-
2 .ad l
3 .nh
4 .SH NAME
5 hwlocality_cpukinds \- Kinds of CPU cores
6 .SH SYNOPSIS
7 .br
8 .PP
9 .SS "Functions"
10
11 .in +1c
12 .ti -1c
13 .RI "int \fBhwloc_cpukinds_get_nr\fP (\fBhwloc_topology_t\fP topology, unsigned long flags)"
14 .br
15 .ti -1c
16 .RI "int \fBhwloc_cpukinds_get_by_cpuset\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_const_bitmap_t\fP cpuset, unsigned long flags)"
17 .br
18 .ti -1c
19 .RI "int \fBhwloc_cpukinds_get_info\fP (\fBhwloc_topology_t\fP topology, unsigned kind_index, \fBhwloc_bitmap_t\fP cpuset, int *efficiency, unsigned *nr_infos, struct \fBhwloc_info_s\fP **infos, unsigned long flags)"
20 .br
21 .ti -1c
22 .RI "int \fBhwloc_cpukinds_register\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_bitmap_t\fP cpuset, int forced_efficiency, unsigned nr_infos, struct \fBhwloc_info_s\fP *infos, unsigned long flags)"
23 .br
24 .in -1c
25 .SH "Detailed Description"
26 .PP
27 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\&.
28
29 .PP
30 The number of kinds may be obtained with \fBhwloc_cpukinds_get_nr()\fP\&. 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\&.
31
32 .PP
33 The index of the kind that describes a given CPU set (if any, and not partially) may be obtained with \fBhwloc_cpukinds_get_by_cpuset()\fP\&.
34
35 .PP
36 From the index of a kind, it is possible to retrieve information with \fBhwloc_cpukinds_get_info()\fP: an abstracted efficiency value, and an array of info attributes (for instance the "CoreType" and "FrequencyMaxMHz", see \fBCPU Kinds\fP)\&.
37
38 .PP
39 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 \fRkind_index\fP to \fBhwloc_cpukinds_get_info()\fP will return information about the CPU kind with lower performance but higher energy-efficiency\&. Higher \fRkind_index\fP values would rather return information about power-hungry high-performance cores\&.
40
41 .PP
42 When available, efficiency values are gathered from the operating system\&. If so, \fRcpukind_efficiency\fP is set in the struct \fBhwloc_topology_discovery_support\fP array\&. This is currently available on Windows 10, Mac OS X (Darwin), and on some Linux platforms where core "capacity" is exposed in sysfs\&.
43
44 .PP
45 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 \fBEnvironment variables for tweaking hwloc heuristics\fP\&.
46
47 .PP
48 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 (\fR-1\fP), and they are not indexed/ordered in any specific way\&.
49 .SH "Function Documentation"
50 .PP
51 .SS "int hwloc_cpukinds_get_by_cpuset (\fBhwloc_topology_t\fP topology, \fBhwloc_const_bitmap_t\fP cpuset, unsigned long flags)"
52
53 .PP
54 Get the index of the CPU kind that contains CPUs listed in \fRcpuset\fP\&. \fRflags\fP must be \fR0\fP for now\&.
55
56 .PP
57 \fBReturns\fP
58 .RS 4
59 The index of the CPU kind (positive integer or 0) on success\&.
60
61 .PP
62 \fR-1\fP with \fRerrno\fP set to \fREXDEV\fP if \fRcpuset\fP is only partially included in the some kind\&.
63
64 .PP
65 \fR-1\fP with \fRerrno\fP set to \fRENOENT\fP if \fRcpuset\fP is not included in any kind, even partially\&.
66
67 .PP
68 \fR-1\fP with \fRerrno\fP set to \fREINVAL\fP if parameters are invalid\&.
69 .RE
70 .PP
71
72 .SS "int hwloc_cpukinds_get_info (\fBhwloc_topology_t\fP topology, unsigned kind_index, \fBhwloc_bitmap_t\fP cpuset, int * efficiency, unsigned * nr_infos, struct \fBhwloc_info_s\fP ** infos, unsigned long flags)"
73
74 .PP
75 Get the CPU set and infos about a CPU kind in the topology\&. \fRkind_index\fP identifies one kind of CPU between 0 and the number of kinds returned by \fBhwloc_cpukinds_get_nr()\fP minus 1\&.
76
77 .PP
78 If not \fRNULL\fP, the bitmap \fRcpuset\fP will be filled with the set of PUs of this kind\&.
79
80 .PP
81 The integer pointed by \fRefficiency\fP, if not \fRNULL\fP will, be filled with the ranking of this kind of CPU in term of efficiency (see above)\&. It ranges from \fR0\fP to the number of kinds (as reported by \fBhwloc_cpukinds_get_nr()\fP) minus 1\&.
82
83 .PP
84 Kinds with lower efficiency are reported first\&.
85
86 .PP
87 If there is a single kind in the topology, its efficiency \fR0\fP\&. If the efficiency of some kinds of cores is unknown, the efficiency of all kinds is set to \fR-1\fP, and kinds are reported in no specific order\&.
88
89 .PP
90 The array of info attributes (for instance the "CoreType", "FrequencyMaxMHz" or "FrequencyBaseMHz", see \fBCPU Kinds\fP) and its length are returned in \fRinfos\fP or \fRnr_infos\fP\&. The array belongs to the topology, it should not be freed or modified\&.
91
92 .PP
93 If \fRnr_infos\fP or \fRinfos\fP is \fRNULL\fP, no info is returned\&.
94
95 .PP
96 \fRflags\fP must be \fR0\fP for now\&.
97
98 .PP
99 \fBReturns\fP
100 .RS 4
101 \fR0\fP on success\&.
102
103 .PP
104 \fR-1\fP with \fRerrno\fP set to \fRENOENT\fP if \fRkind_index\fP does not match any CPU kind\&.
105
106 .PP
107 \fR-1\fP with \fRerrno\fP set to \fREINVAL\fP if parameters are invalid\&.
108 .RE
109 .PP
110
111 .SS "int hwloc_cpukinds_get_nr (\fBhwloc_topology_t\fP topology, unsigned long flags)"
112
113 .PP
114 Get the number of different kinds of CPU cores in the topology\&. \fRflags\fP must be \fR0\fP for now\&.
115
116 .PP
117 \fBReturns\fP
118 .RS 4
119 The number of CPU kinds (positive integer) on success\&.
120
121 .PP
122 \fR0\fP if no information about kinds was found\&.
123
124 .PP
125 \fR-1\fP with \fRerrno\fP set to \fREINVAL\fP if \fRflags\fP is invalid\&.
126 .RE
127 .PP
128
129 .SS "int hwloc_cpukinds_register (\fBhwloc_topology_t\fP topology, \fBhwloc_bitmap_t\fP cpuset, int forced_efficiency, unsigned nr_infos, struct \fBhwloc_info_s\fP * infos, unsigned long flags)"
130
131 .PP
132 Register a kind of CPU in the topology\&. Mark the PUs listed in \fRcpuset\fP as being of the same kind with respect to the given attributes\&.
133
134 .PP
135 \fRforced_efficiency\fP should be \fR-1\fP 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\&.
136
137 .PP
138 The array \fRinfos\fP of size \fRnr_infos\fP may be used to provide info names and values describing this kind of PUs\&.
139
140 .PP
141 \fRflags\fP must be \fR0\fP for now\&.
142
143 .PP
144 Parameters \fRcpuset\fP and \fRinfos\fP will be duplicated internally, the caller is responsible for freeing them\&.
145
146 .PP
147 If \fRcpuset\fP 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\&.
148
149 .PP
150 \fBNote\fP
151 .RS 4
152 The efficiency \fRforced_efficiency\fP provided to this function may be different from the one reported later by \fBhwloc_cpukinds_get_info()\fP because hwloc will scale efficiency values down to between 0 and the number of kinds minus 1\&.
153 .RE
154 .PP
155 \fBReturns\fP
156 .RS 4
157 \fR0\fP on success\&.
158
159 .PP
160 \fR-1\fP with \fRerrno\fP set to \fREINVAL\fP if some parameters are invalid, for instance if \fRcpuset\fP is \fRNULL\fP or empty\&.
161 .RE
162 .PP
163
164 .SH "Author"
165 .PP
166 Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.