| 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\&. |