Debian Codegraph @

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

raw
1 .TH "hwloc_obj" 3 "Version 2.14.0" "Hardware Locality (hwloc)" \" -*- nroff -*-
2 .ad l
3 .nh
4 .SH NAME
5 hwloc_obj
6 .SH SYNOPSIS
7 .br
8 .PP
9 .PP
10 \fR#include <hwloc\&.h>\fP
11 .SS "Data Fields"
12
13 .in +1c
14 .ti -1c
15 .RI "\fBhwloc_obj_type_t\fP \fBtype\fP"
16 .br
17 .ti -1c
18 .RI "char * \fBsubtype\fP"
19 .br
20 .ti -1c
21 .RI "unsigned \fBos_index\fP"
22 .br
23 .ti -1c
24 .RI "char * \fBname\fP"
25 .br
26 .ti -1c
27 .RI "hwloc_uint64_t \fBtotal_memory\fP"
28 .br
29 .ti -1c
30 .RI "union \fBhwloc_obj_attr_u\fP * \fBattr\fP"
31 .br
32 .ti -1c
33 .RI "int \fBdepth\fP"
34 .br
35 .ti -1c
36 .RI "unsigned \fBlogical_index\fP"
37 .br
38 .ti -1c
39 .RI "struct \fBhwloc_obj\fP * \fBnext_cousin\fP"
40 .br
41 .ti -1c
42 .RI "struct \fBhwloc_obj\fP * \fBprev_cousin\fP"
43 .br
44 .ti -1c
45 .RI "struct \fBhwloc_obj\fP * \fBparent\fP"
46 .br
47 .ti -1c
48 .RI "unsigned \fBsibling_rank\fP"
49 .br
50 .ti -1c
51 .RI "struct \fBhwloc_obj\fP * \fBnext_sibling\fP"
52 .br
53 .ti -1c
54 .RI "struct \fBhwloc_obj\fP * \fBprev_sibling\fP"
55 .br
56 .ti -1c
57 .RI "int \fBsymmetric_subtree\fP"
58 .br
59 .ti -1c
60 .RI "\fBhwloc_cpuset_t\fP \fBcpuset\fP"
61 .br
62 .ti -1c
63 .RI "\fBhwloc_cpuset_t\fP \fBcomplete_cpuset\fP"
64 .br
65 .ti -1c
66 .RI "\fBhwloc_nodeset_t\fP \fBnodeset\fP"
67 .br
68 .ti -1c
69 .RI "\fBhwloc_nodeset_t\fP \fBcomplete_nodeset\fP"
70 .br
71 .ti -1c
72 .RI "struct \fBhwloc_info_s\fP * \fBinfos\fP"
73 .br
74 .ti -1c
75 .RI "unsigned \fBinfos_count\fP"
76 .br
77 .ti -1c
78 .RI "void * \fBuserdata\fP"
79 .br
80 .ti -1c
81 .RI "hwloc_uint64_t \fBgp_index\fP"
82 .br
83 .in -1c
84 .PP
85 .RI "\fBList and array of normal children below this object (except Memory, I/O and Misc children)\&.\fP"
86 .br
87
88 .in +1c
89 .in +1c
90 .ti -1c
91 .RI "unsigned \fBarity\fP"
92 .br
93 .ti -1c
94 .RI "struct \fBhwloc_obj\fP ** \fBchildren\fP"
95 .br
96 .ti -1c
97 .RI "struct \fBhwloc_obj\fP * \fBfirst_child\fP"
98 .br
99 .ti -1c
100 .RI "struct \fBhwloc_obj\fP * \fBlast_child\fP"
101 .br
102 .in -1c
103 .in -1c
104 .PP
105 .RI "\fBList of Memory children below this object\&.\fP"
106 .br
107
108 .in +1c
109 .in +1c
110 .ti -1c
111 .RI "unsigned \fBmemory_arity\fP"
112 .br
113 .ti -1c
114 .RI "struct \fBhwloc_obj\fP * \fBmemory_first_child\fP"
115 .br
116 .in -1c
117 .in -1c
118 .PP
119 .RI "\fBList of I/O children below this object\&.\fP"
120 .br
121
122 .in +1c
123 .in +1c
124 .ti -1c
125 .RI "unsigned \fBio_arity\fP"
126 .br
127 .ti -1c
128 .RI "struct \fBhwloc_obj\fP * \fBio_first_child\fP"
129 .br
130 .in -1c
131 .in -1c
132 .PP
133 .RI "\fBList of Misc children below this object\&.\fP"
134 .br
135
136 .in +1c
137 .in +1c
138 .ti -1c
139 .RI "unsigned \fBmisc_arity\fP"
140 .br
141 .ti -1c
142 .RI "struct \fBhwloc_obj\fP * \fBmisc_first_child\fP"
143 .br
144 .in -1c
145 .in -1c
146 .SH "Detailed Description"
147 .PP
148 Structure of a topology object\&.
149
150 Applications must not modify any field except \fR\fBhwloc_obj\&.userdata\fP\fP\&.
151 .SH "Field Documentation"
152 .PP
153 .SS "unsigned hwloc_obj::arity"
154
155 .PP
156 Number of normal children\&. Memory, Misc and I/O children are not listed here but rather in their dedicated children list\&.
157 .SS "union \fBhwloc_obj_attr_u\fP* hwloc_obj::attr"
158
159 .PP
160 Object type-specific Attributes, may be \fRNULL\fP if no attribute value was found\&.
161 .SS "struct \fBhwloc_obj\fP** hwloc_obj::children"
162
163 .PP
164 Normal children, \fRchildren\fP[0 \&.\&. arity -1]\&.
165 .SS "\fBhwloc_cpuset_t\fP hwloc_obj::complete_cpuset"
166
167 .PP
168 The complete CPU set of processors of this object,\&. This may include not only the same as the cpuset field, but also some CPUs for which topology information is unknown or incomplete, some offlines CPUs, and the CPUs that are ignored when the \fBHWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED\fP flag is not set\&. Thus no corresponding PU object may be found in the topology, because the precise position is undefined\&. It is however known that it would be somewhere under this object\&.
169
170 .PP
171 \fBNote\fP
172 .RS 4
173 Its value must not be changed, \fBhwloc_bitmap_dup()\fP must be used instead\&.
174 .RE
175 .PP
176
177 .SS "\fBhwloc_nodeset_t\fP hwloc_obj::complete_nodeset"
178
179 .PP
180 The complete NUMA node set of this object,\&. This may include not only the same as the nodeset field, but also some NUMA nodes for which topology information is unknown or incomplete, some offlines nodes, and the nodes that are ignored when the \fBHWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED\fP flag is not set\&. Thus no corresponding NUMA node object may be found in the topology, because the precise position is undefined\&. It is however known that it would be somewhere under this object\&.
181
182 .PP
183 If there are no NUMA nodes in the machine, all the memory is close to this object, so only the first bit is set in \fRcomplete_nodeset\fP\&.
184
185 .PP
186 \fBNote\fP
187 .RS 4
188 Its value must not be changed, \fBhwloc_bitmap_dup()\fP must be used instead\&.
189 .RE
190 .PP
191
192 .SS "\fBhwloc_cpuset_t\fP hwloc_obj::cpuset"
193
194 .PP
195 CPUs covered by this object\&. This is the set of CPUs for which there are PU objects in the topology under this object, i\&.e\&. which are known to be physically contained in this object and known how (the children path between this object and the PU objects)\&.
196
197 .PP
198 If the \fBHWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED\fP configuration flag is set, some of these CPUs may be online but not allowed for binding, see \fBhwloc_topology_get_allowed_cpuset()\fP\&.
199
200 .PP
201 \fBNote\fP
202 .RS 4
203 All objects have non-NULL CPU and node sets except Misc and I/O objects\&.
204
205 .PP
206 Its value must not be changed, \fBhwloc_bitmap_dup()\fP must be used instead\&.
207 .RE
208 .PP
209
210 .SS "int hwloc_obj::depth"
211
212 .PP
213 Vertical index in the hierarchy\&. For normal objects, this is the depth of the horizontal level that contains this object and its cousins of the same type\&. If the topology is symmetric, this is equal to the parent depth plus one, and also equal to the number of parent/child links from the root object to here\&.
214
215 .PP
216 For special objects (NUMA nodes, I/O and Misc) that are not in the main tree, this is a special negative value that corresponds to their dedicated level, see \fBhwloc_get_type_depth()\fP and \fBhwloc_get_type_depth_e\fP\&. Those special values can be passed to hwloc functions such \fBhwloc_get_nbobjs_by_depth()\fP as usual\&.
217 .SS "struct \fBhwloc_obj\fP* hwloc_obj::first_child"
218
219 .PP
220 First normal child\&.
221 .SS "hwloc_uint64_t hwloc_obj::gp_index"
222
223 .PP
224 Global persistent index\&. Generated by hwloc, unique across the topology (contrary to os_index) and persistent across topology changes (contrary to logical_index)\&. Mostly used internally, but could also be used by application to identify objects\&.
225 .SS "struct \fBhwloc_info_s\fP* hwloc_obj::infos"
226
227 .PP
228 Array of info attributes (name and value strings)\&.
229 .SS "unsigned hwloc_obj::infos_count"
230
231 .PP
232 Size of infos array\&.
233 .SS "unsigned hwloc_obj::io_arity"
234
235 .PP
236 Number of I/O children\&. These children are listed in \fRio_first_child\fP\&.
237 .SS "struct \fBhwloc_obj\fP* hwloc_obj::io_first_child"
238
239 .PP
240 First I/O child\&. Bridges, PCI and OS devices are listed here (\fRio_arity\fP and \fRio_first_child\fP) instead of in the normal children list\&. See also \fBhwloc_obj_type_is_io()\fP\&.
241 .SS "struct \fBhwloc_obj\fP* hwloc_obj::last_child"
242
243 .PP
244 Last normal child\&.
245 .SS "unsigned hwloc_obj::logical_index"
246
247 .PP
248 Horizontal index in the whole list of similar objects, hence guaranteed unique across the entire machine\&. Could be a "cousin_rank" since it's the rank within the "cousin" list below Note that this index may change when restricting the topology or when inserting a group\&.
249 .SS "unsigned hwloc_obj::memory_arity"
250
251 .PP
252 Number of Memory children\&. These children are listed in \fRmemory_first_child\fP\&.
253 .SS "struct \fBhwloc_obj\fP* hwloc_obj::memory_first_child"
254
255 .PP
256 First Memory child\&. NUMA nodes and Memory-side caches are listed here (\fRmemory_arity\fP and \fRmemory_first_child\fP) instead of in the normal children list\&. See also \fBhwloc_obj_type_is_memory()\fP\&. A memory hierarchy starts from a normal CPU-side object (e\&.g\&. Package) and ends with NUMA nodes as leaves\&. There might exist some memory-side caches between them in the middle of the memory subtree\&.
257 .SS "unsigned hwloc_obj::misc_arity"
258
259 .PP
260 Number of Misc children\&. These children are listed in \fRmisc_first_child\fP\&.
261 .SS "struct \fBhwloc_obj\fP* hwloc_obj::misc_first_child"
262
263 .PP
264 First Misc child\&. Misc objects are listed here (\fRmisc_arity\fP and \fRmisc_first_child\fP) instead of in the normal children list\&.
265 .SS "char* hwloc_obj::name"
266
267 .PP
268 Object-specific name if any\&. Mostly used for identifying OS devices and Misc objects where a name string is more useful than numerical indexes\&.
269 .SS "struct \fBhwloc_obj\fP* hwloc_obj::next_cousin"
270
271 .PP
272 Next object of same type and depth\&.
273 .SS "struct \fBhwloc_obj\fP* hwloc_obj::next_sibling"
274
275 .PP
276 Next object below the same parent (inside the same list of children)\&.
277 .SS "\fBhwloc_nodeset_t\fP hwloc_obj::nodeset"
278
279 .PP
280 NUMA nodes covered by this object or containing this object\&. This is the set of NUMA nodes for which there are NUMA node objects in the topology under or above this object, i\&.e\&. which are known to be physically contained in this object or containing it and known how (the children path between this object and the NUMA node objects)\&.
281
282 .PP
283 In the end, these nodes are those that are close to the current object\&. Function \fBhwloc_get_local_numanode_objs()\fP may be used to list those NUMA nodes more precisely\&.
284
285 .PP
286 If the \fBHWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED\fP configuration flag is set, some of these nodes may be online but not allowed for allocation, see \fBhwloc_topology_get_allowed_nodeset()\fP\&.
287
288 .PP
289 If there are no NUMA nodes in the machine, all the memory is close to this object, so only the first bit may be set in \fRnodeset\fP\&.
290
291 .PP
292 \fBNote\fP
293 .RS 4
294 All objects have non-NULL CPU and node sets except Misc and I/O objects\&.
295
296 .PP
297 Its value must not be changed, \fBhwloc_bitmap_dup()\fP must be used instead\&.
298 .RE
299 .PP
300
301 .SS "unsigned hwloc_obj::os_index"
302
303 .PP
304 OS-provided physical index number\&. It is not guaranteed unique across the entire machine, except for PUs and NUMA nodes\&. Set to HWLOC_UNKNOWN_INDEX if unknown or irrelevant for this object\&.
305 .SS "struct \fBhwloc_obj\fP* hwloc_obj::parent"
306
307 .PP
308 Parent, \fRNULL\fP if root (Machine object)\&.
309 .SS "struct \fBhwloc_obj\fP* hwloc_obj::prev_cousin"
310
311 .PP
312 Previous object of same type and depth\&.
313 .SS "struct \fBhwloc_obj\fP* hwloc_obj::prev_sibling"
314
315 .PP
316 Previous object below the same parent (inside the same list of children)\&.
317 .SS "unsigned hwloc_obj::sibling_rank"
318
319 .PP
320 Index in parent's \fRchildren\fP[] array\&. Or the index in parent's Memory, I/O or Misc children list\&.
321 .SS "char* hwloc_obj::subtype"
322
323 .PP
324 Subtype string to better describe the type field\&.
325 .SS "int hwloc_obj::symmetric_subtree"
326
327 .PP
328 Set if the subtree of normal objects below this object is symmetric, which means all normal children and their children have identical subtrees\&. Memory, I/O and Misc children are ignored\&.
329
330 .PP
331 If set in the topology root object, lstopo may export the topology as a synthetic string\&.
332 .SS "hwloc_uint64_t hwloc_obj::total_memory"
333
334 .PP
335 Total memory (in bytes) in NUMA nodes below this object\&.
336 .SS "\fBhwloc_obj_type_t\fP hwloc_obj::type"
337
338 .PP
339 Type of object\&.
340 .SS "void* hwloc_obj::userdata"
341
342 .PP
343 Application-given private data pointer, initialized to \fRNULL\fP, use it as you wish\&. See \fBhwloc_topology_set_userdata_export_callback()\fP in \fBhwloc/export\&.h\fP if you wish to export this field to XML\&.
344
345 .SH "Author"
346 .PP
347 Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.