Debian Codegraph @

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

raw
1 .TH "hwlocality_tinker" 3 "Version 2.14.0" "Hardware Locality (hwloc)" \" -*- nroff -*-
2 .ad l
3 .nh
4 .SH NAME
5 hwlocality_tinker \- Modifying a loaded Topology
6 .SH SYNOPSIS
7 .br
8 .PP
9 .SS "Enumerations"
10
11 .in +1c
12 .ti -1c
13 .RI "enum \fBhwloc_restrict_flags_e\fP { \fBHWLOC_RESTRICT_FLAG_REMOVE_CPULESS\fP, \fBHWLOC_RESTRICT_FLAG_BYNODESET\fP = (1UL<<3), \fBHWLOC_RESTRICT_FLAG_REMOVE_MEMLESS\fP, \fBHWLOC_RESTRICT_FLAG_ADAPT_MISC\fP, \fBHWLOC_RESTRICT_FLAG_ADAPT_IO\fP }"
14 .br
15 .ti -1c
16 .RI "enum \fBhwloc_allow_flags_e\fP { \fBHWLOC_ALLOW_FLAG_ALL\fP, \fBHWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS\fP, \fBHWLOC_ALLOW_FLAG_CUSTOM\fP }"
17 .br
18 .in -1c
19 .SS "Functions"
20
21 .in +1c
22 .ti -1c
23 .RI "int \fBhwloc_topology_restrict\fP (\fBhwloc_topology_t\fP restrict topology, \fBhwloc_const_bitmap_t\fP set, unsigned long flags)"
24 .br
25 .ti -1c
26 .RI "int \fBhwloc_topology_allow\fP (\fBhwloc_topology_t\fP restrict topology, \fBhwloc_const_cpuset_t\fP cpuset, \fBhwloc_const_nodeset_t\fP nodeset, unsigned long flags)"
27 .br
28 .ti -1c
29 .RI "\fBhwloc_obj_t\fP \fBhwloc_topology_insert_misc_object\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_obj_t\fP parent, const char *name)"
30 .br
31 .ti -1c
32 .RI "\fBhwloc_obj_t\fP \fBhwloc_topology_alloc_group_object\fP (\fBhwloc_topology_t\fP topology)"
33 .br
34 .ti -1c
35 .RI "int \fBhwloc_topology_free_group_object\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_obj_t\fP group)"
36 .br
37 .ti -1c
38 .RI "\fBhwloc_obj_t\fP \fBhwloc_topology_insert_group_object\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_obj_t\fP group)"
39 .br
40 .ti -1c
41 .RI "int \fBhwloc_obj_add_other_obj_sets\fP (\fBhwloc_obj_t\fP dst, \fBhwloc_obj_t\fP src)"
42 .br
43 .ti -1c
44 .RI "int \fBhwloc_topology_refresh\fP (\fBhwloc_topology_t\fP topology)"
45 .br
46 .in -1c
47 .SH "Detailed Description"
48 .PP
49
50 .SH "Enumeration Type Documentation"
51 .PP
52 .SS "enum \fBhwloc_allow_flags_e\fP"
53
54 .PP
55 Flags to be given to \fBhwloc_topology_allow()\fP\&.
56 .PP
57 \fBEnumerator\fP
58 .in +1c
59 .TP
60 \f(BIHWLOC_ALLOW_FLAG_ALL \fP
61 Mark all objects as allowed in the topology\&. \fRcpuset\fP and \fRnođeset\fP given to \fBhwloc_topology_allow()\fP must be \fRNULL\fP\&.
62 .TP
63 \f(BIHWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS \fP
64 Only allow objects that are available to the current process\&. The topology must have \fBHWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM\fP so that the set of available resources can actually be retrieved from the operating system\&.
65
66 .PP
67 \fRcpuset\fP and \fRnođeset\fP given to \fBhwloc_topology_allow()\fP must be \fRNULL\fP\&.
68 .TP
69 \f(BIHWLOC_ALLOW_FLAG_CUSTOM \fP
70 Allow a custom set of objects, given to \fBhwloc_topology_allow()\fP as \fRcpuset\fP and/or \fRnodeset\fP parameters\&.
71 .SS "enum \fBhwloc_restrict_flags_e\fP"
72
73 .PP
74 Flags to be given to \fBhwloc_topology_restrict()\fP\&.
75 .PP
76 \fBEnumerator\fP
77 .in +1c
78 .TP
79 \f(BIHWLOC_RESTRICT_FLAG_REMOVE_CPULESS \fP
80 Remove all objects that became CPU-less\&. By default, only objects that contain no PU and no memory are removed\&. This flag may not be used with \fBHWLOC_RESTRICT_FLAG_BYNODESET\fP\&.
81 .TP
82 \f(BIHWLOC_RESTRICT_FLAG_BYNODESET \fP
83 Restrict by nodeset instead of CPU set\&. Only keep objects whose nodeset is included or partially included in the given set\&. This flag may not be used with \fBHWLOC_RESTRICT_FLAG_REMOVE_CPULESS\fP\&.
84 .TP
85 \f(BIHWLOC_RESTRICT_FLAG_REMOVE_MEMLESS \fP
86 Remove all objects that became Memory-less\&. By default, only objects that contain no PU and no memory are removed\&. This flag may only be used with \fBHWLOC_RESTRICT_FLAG_BYNODESET\fP\&.
87 .TP
88 \f(BIHWLOC_RESTRICT_FLAG_ADAPT_MISC \fP
89 Move Misc objects to ancestors if their parents are removed during restriction\&. If this flag is not set, Misc objects are removed when their parents are removed\&.
90 .TP
91 \f(BIHWLOC_RESTRICT_FLAG_ADAPT_IO \fP
92 Move I/O objects to ancestors if their parents are removed during restriction\&. If this flag is not set, I/O devices and bridges are removed when their parents are removed\&.
93 .SH "Function Documentation"
94 .PP
95 .SS "int hwloc_obj_add_other_obj_sets (\fBhwloc_obj_t\fP dst, \fBhwloc_obj_t\fP src)"
96
97 .PP
98 Setup object cpusets/nodesets by OR'ing another object's sets\&. For each defined cpuset or nodeset in \fRsrc\fP, allocate the corresponding set in \fRdst\fP and add \fRsrc\fP to it by OR'ing sets\&.
99
100 .PP
101 This function is convenient between \fBhwloc_topology_alloc_group_object()\fP and \fBhwloc_topology_insert_group_object()\fP\&. It builds the sets of the new Group that will be inserted as a new intermediate parent of several objects\&.
102
103 .PP
104 \fBReturns\fP
105 .RS 4
106 0 on success\&.
107
108 .PP
109 -1 with errno set to \fRENOMEM\fP if some internal reallocation failed\&.
110 .RE
111 .PP
112
113 .SS "\fBhwloc_obj_t\fP hwloc_topology_alloc_group_object (\fBhwloc_topology_t\fP topology)"
114
115 .PP
116 Allocate a Group object to insert later with \fBhwloc_topology_insert_group_object()\fP\&. This function returns a new Group object\&.
117
118 .PP
119 The caller should (at least) initialize its sets before inserting the object in the topology, see \fBhwloc_topology_insert_group_object()\fP\&. Or it may decide not to insert and just free the group object by calling \fBhwloc_topology_free_group_object()\fP\&.
120
121 .PP
122 \fBReturns\fP
123 .RS 4
124 The allocated object on success\&.
125
126 .PP
127 \fRNULL\fP on error\&.
128 .RE
129 .PP
130 \fBNote\fP
131 .RS 4
132 If successfully inserted by \fBhwloc_topology_insert_group_object()\fP, the object will be freed when the entire topology is freed\&. If insertion failed (e\&.g\&. \fRNULL\fP or empty CPU and node-sets), it is freed before returning the error\&.
133 .RE
134 .PP
135
136 .SS "int hwloc_topology_allow (\fBhwloc_topology_t\fP restrict topology, \fBhwloc_const_cpuset_t\fP cpuset, \fBhwloc_const_nodeset_t\fP nodeset, unsigned long flags)"
137
138 .PP
139 Change the sets of allowed PUs and NUMA nodes in the topology\&. This function only works if the \fBHWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED\fP was set on the topology\&. It does not modify any object, it only changes the sets returned by \fBhwloc_topology_get_allowed_cpuset()\fP and \fBhwloc_topology_get_allowed_nodeset()\fP\&.
140
141 .PP
142 It is notably useful when importing a topology from another process running in a different Linux Cgroup\&.
143
144 .PP
145 \fRflags\fP must be set to one flag among \fBhwloc_allow_flags_e\fP\&.
146
147 .PP
148 \fBReturns\fP
149 .RS 4
150 0 on success, -1 on error\&.
151 .RE
152 .PP
153 \fBNote\fP
154 .RS 4
155 Removing objects from a topology should rather be performed with \fBhwloc_topology_restrict()\fP\&.
156 .RE
157 .PP
158
159 .SS "int hwloc_topology_free_group_object (\fBhwloc_topology_t\fP topology, \fBhwloc_obj_t\fP group)"
160
161 .PP
162 Free a group object allocated with \fBhwloc_topology_alloc_group_object()\fP\&. This function is only useful if the group object was not given to \fBhwloc_topology_insert_group_object()\fP as planned\&.
163
164 .PP
165 \fBNote\fP
166 .RS 4
167 \fRtopology\fP must be the same as the one previously passed to \fBhwloc_topology_alloc_group_object()\fP\&.
168 .RE
169 .PP
170 \fBReturns\fP
171 .RS 4
172 \fR0\fP on success\&.
173
174 .PP
175 \fR-1\fP on error, for instance if an invalid topology is given\&.
176 .RE
177 .PP
178
179 .SS "\fBhwloc_obj_t\fP hwloc_topology_insert_group_object (\fBhwloc_topology_t\fP topology, \fBhwloc_obj_t\fP group)"
180
181 .PP
182 Add more structure to the topology by adding an intermediate Group\&. The caller should first allocate a new Group object with \fBhwloc_topology_alloc_group_object()\fP\&. Then it must setup at least one of its CPU or node sets to specify the final location of the Group in the topology\&. Then the object can be passed to this function for actual insertion in the topology\&.
183
184 .PP
185 The main use case for this function is to group a subset of siblings among the list of children below a single parent\&. For instance, if grouping 4 cores out of a 8-core socket, the logical list of cores will be reordered so that the 4 grouped ones are consecutive\&. Then, if needed, a new depth is added between the parent and those children, and the Group is inserted there\&. At the end, the 4 grouped cores are now children of the Group, which replaces them as a child of the original parent\&.
186
187 .PP
188 In practice, the grouped objects are specified through cpusets and/or nodesets, for instance using \fBhwloc_obj_add_other_obj_sets()\fP iteratively\&. Hence it is possible to group objects that are not children of the same parent, for instance some PUs below the 4 cores in example above\&. However this general case may fail if the expected Group conflicts with the existing hierarchy\&. For instance if each core has two PUs, it is not possible to insert a Group containing a single PU of each core\&.
189
190 .PP
191 To specify the objects to group, either the cpuset or nodeset field (or both, if compatible) must be set to a non-empty bitmap\&. The complete_cpuset or complete_nodeset may be set instead if inserting with respect to the complete topology (including disallowed, offline or unknown objects)\&. These sets cannot be larger than the current topology, or they would get restricted silently\&. The core will setup the other sets after actual insertion\&.
192
193 .PP
194 The \fRsubtype\fP object attribute may be defined with \fBhwloc_obj_set_subtype()\fP to display something else than "Group" as the type name for this object in lstopo\&. Custom name-value info pairs may be added with \fBhwloc_obj_add_info()\fP after insertion\&.
195
196 .PP
197 The group \fRdont_merge\fP attribute may be set to \fR1\fP to prevent the hwloc core from ever merging this object with another hierarchically-identical object\&. This is useful when the Group itself describes an important feature that cannot be exposed anywhere else in the hierarchy\&.
198
199 .PP
200 The group \fRkind\fP attribute may be set to a high value such as \fR0xffffffff\fP to tell hwloc that this new Group should always be discarded in favor of any existing Group with the same locality\&.
201
202 .PP
203 \fBNote\fP
204 .RS 4
205 Inserting a group adds some locality information to the topology, hence the existing objects may get reordered (including PUs and NUMA nodes), and their logical indexes may change\&.
206
207 .PP
208 If the insertion fails, the input group object is freed\&.
209
210 .PP
211 If the group object should be discarded instead of inserted, it may be passed to \fBhwloc_topology_free_group_object()\fP instead\&.
212
213 .PP
214 \fRtopology\fP must be the same as the one previously passed to \fBhwloc_topology_alloc_group_object()\fP\&.
215 .RE
216 .PP
217 \fBReturns\fP
218 .RS 4
219 The inserted object if it was properly inserted\&.
220
221 .PP
222 An existing object if the Group was merged or discarded because the topology already contained an object at the same location (the Group did not add any hierarchy information)\&.
223
224 .PP
225 \fRNULL\fP if the insertion failed because of conflicting sets in topology tree\&.
226
227 .PP
228 \fRNULL\fP if Group objects are filtered-out of the topology (\fBHWLOC_TYPE_FILTER_KEEP_NONE\fP)\&.
229
230 .PP
231 \fRNULL\fP if the object was discarded because no set was initialized in the Group before insert, or all of them were empty\&.
232 .RE
233 .PP
234
235 .SS "\fBhwloc_obj_t\fP hwloc_topology_insert_misc_object (\fBhwloc_topology_t\fP topology, \fBhwloc_obj_t\fP parent, const char * name)"
236
237 .PP
238 Add a MISC object as a leaf of the topology\&. A new MISC object will be created and inserted into the topology at the position given by parent\&. It is appended to the list of existing Misc children, without ever adding any intermediate hierarchy level\&. This is useful for annotating the topology without actually changing the hierarchy\&.
239
240 .PP
241 \fRname\fP is supposed to be unique across all Misc objects in the topology\&. It will be duplicated to setup the new object attributes\&.
242
243 .PP
244 The new leaf object will not have any \fRcpuset\fP\&.
245
246 .PP
247 The \fRsubtype\fP object attribute may be defined with \fBhwloc_obj_set_subtype()\fP after successful insertion\&.
248
249 .PP
250 \fBReturns\fP
251 .RS 4
252 the newly-created object
253
254 .PP
255 \fRNULL\fP on error\&.
256
257 .PP
258 \fRNULL\fP if Misc objects are filtered-out of the topology (\fBHWLOC_TYPE_FILTER_KEEP_NONE\fP)\&.
259 .RE
260 .PP
261 \fBNote\fP
262 .RS 4
263 If \fRname\fP contains some non-printable characters, they will be dropped when exporting to XML, see \fBhwloc_topology_export_xml()\fP in \fBhwloc/export\&.h\fP\&.
264 .RE
265 .PP
266
267 .SS "int hwloc_topology_refresh (\fBhwloc_topology_t\fP topology)"
268
269 .PP
270 Refresh internal structures after topology modification\&. Modifying the topology (by restricting, adding objects, modifying structures such as distances or memory attributes, etc\&.) may cause some internal caches to become invalid\&. These caches are automatically refreshed when accessed but this refreshing is not thread-safe\&.
271
272 .PP
273 This function is not thread-safe either, but it is a good way to end a non-thread-safe phase of topology modification\&. Once this refresh is done, multiple threads may concurrently consult the topology, objects, distances, attributes, etc\&.
274
275 .PP
276 See also \fBThread Safety\fP
277
278 .PP
279 \fBReturns\fP
280 .RS 4
281 0 on success\&.
282
283 .PP
284 -1 on error, for instance if some internal reallocation failed\&.
285 .RE
286 .PP
287
288 .SS "int hwloc_topology_restrict (\fBhwloc_topology_t\fP restrict topology, \fBhwloc_const_bitmap_t\fP set, unsigned long flags)"
289
290 .PP
291 Restrict the topology to the given CPU set or nodeset\&. Topology \fRtopology\fP is modified so as to remove all objects that are not included (or partially included) in the CPU set \fRset\fP\&. All objects CPU and node sets are restricted accordingly\&.
292
293 .PP
294 By default, \fRset\fP is a CPU set\&. It means that the set of PUs in the topology is restricted\&. Once some PUs got removed, their parents may also get removed recursively if they became child-less\&.
295
296 .PP
297 If \fBHWLOC_RESTRICT_FLAG_BYNODESET\fP is passed in \fRflags\fP, \fRset\fP is considered a nodeset instead of a CPU set\&. It means that the set of NUMA nodes in the topology is restricted (instead of PUs)\&. Once some NUMA nodes got removed, their parents may also get removed recursively if they became child-less\&.
298
299 .PP
300 \fRflags\fP is a OR'ed set of \fBhwloc_restrict_flags_e\fP\&.
301
302 .PP
303 \fBNote\fP
304 .RS 4
305 Restricting the topology removes some locality information, hence the remaining objects may get reordered (including PUs and NUMA nodes), and their logical indexes may change\&.
306
307 .PP
308 This call may not be reverted by restricting back to a larger set\&. Once dropped during restriction, objects may not be brought back, except by loading another topology with \fBhwloc_topology_load()\fP\&.
309 .RE
310 .PP
311 \fBReturns\fP
312 .RS 4
313 0 on success\&.
314
315 .PP
316 -1 with errno set to \fREINVAL\fP if the input set is invalid\&. The topology is not modified in this case\&.
317
318 .PP
319 -1 with errno set to \fRENOMEM\fP on failure to allocate internal data\&. The topology is reinitialized in this case\&. It should be either destroyed with \fBhwloc_topology_destroy()\fP or configured and loaded again\&.
320 .RE
321 .PP
322
323 .SH "Author"
324 .PP
325 Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.