| 1 |
.TH "hwlocality_components_core_funcs" 3 "Version 2.14.0" "Hardware Locality (hwloc)" \" -*- nroff -*- |
| 2 |
.ad l |
| 3 |
.nh |
| 4 |
.SH NAME |
| 5 |
hwlocality_components_core_funcs \- Components and Plugins: Core functions to be used by components |
| 6 |
.SH SYNOPSIS |
| 7 |
.br |
| 8 |
.PP |
| 9 |
.SS "Macros" |
| 10 |
|
| 11 |
.in +1c |
| 12 |
.ti -1c |
| 13 |
.RI "#define \fBHWLOC_SHOW_CRITICAL_ERRORS\fP()" |
| 14 |
.br |
| 15 |
.ti -1c |
| 16 |
.RI "#define \fBHWLOC_SHOW_ALL_ERRORS\fP()" |
| 17 |
.br |
| 18 |
.in -1c |
| 19 |
.SS "Functions" |
| 20 |
|
| 21 |
.in +1c |
| 22 |
.ti -1c |
| 23 |
.RI "int \fBhwloc_hide_errors\fP (void)" |
| 24 |
.br |
| 25 |
.ti -1c |
| 26 |
.RI "\fBhwloc_obj_t\fP \fBhwloc__insert_object_by_cpuset\fP (struct hwloc_topology *topology, \fBhwloc_obj_t\fP root, \fBhwloc_obj_t\fP obj, const char *reason)" |
| 27 |
.br |
| 28 |
.ti -1c |
| 29 |
.RI "void \fBhwloc_insert_object_by_parent\fP (struct hwloc_topology *topology, \fBhwloc_obj_t\fP parent, \fBhwloc_obj_t\fP obj)" |
| 30 |
.br |
| 31 |
.ti -1c |
| 32 |
.RI "\fBhwloc_obj_t\fP \fBhwloc_alloc_setup_object\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_obj_type_t\fP type, unsigned os_index)" |
| 33 |
.br |
| 34 |
.ti -1c |
| 35 |
.RI "int \fBhwloc_obj_add_children_sets\fP (\fBhwloc_obj_t\fP obj)" |
| 36 |
.br |
| 37 |
.ti -1c |
| 38 |
.RI "int \fBhwloc_topology_reconnect\fP (\fBhwloc_topology_t\fP topology, unsigned long flags)" |
| 39 |
.br |
| 40 |
.in -1c |
| 41 |
.SH "Detailed Description" |
| 42 |
.PP |
| 43 |
|
| 44 |
.PP |
| 45 |
\fBNote\fP |
| 46 |
.RS 4 |
| 47 |
These structures and functions may change when \fBHWLOC_COMPONENT_ABI\fP is modified\&. |
| 48 |
.RE |
| 49 |
.PP |
| 50 |
|
| 51 |
.SH "Macro Definition Documentation" |
| 52 |
.PP |
| 53 |
.SS "#define HWLOC_SHOW_ALL_ERRORS()" |
| 54 |
\fBValue:\fP |
| 55 |
.nf |
| 56 |
(hwloc_hide_errors() == 0) |
| 57 |
.PP |
| 58 |
.fi |
| 59 |
|
| 60 |
.SS "#define HWLOC_SHOW_CRITICAL_ERRORS()" |
| 61 |
\fBValue:\fP |
| 62 |
.nf |
| 63 |
(hwloc_hide_errors() < 2) |
| 64 |
.PP |
| 65 |
.fi |
| 66 |
|
| 67 |
.SH "Function Documentation" |
| 68 |
.PP |
| 69 |
.SS "\fBhwloc_obj_t\fP hwloc__insert_object_by_cpuset (struct hwloc_topology * topology, \fBhwloc_obj_t\fP root, \fBhwloc_obj_t\fP obj, const char * reason)" |
| 70 |
|
| 71 |
.PP |
| 72 |
Add an object to the topology\&. Insert new object \fRobj\fP in the topology starting under existing object \fRroot\fP (if \fRNULL\fP, the topology root object is used)\&. |
| 73 |
|
| 74 |
.PP |
| 75 |
It is sorted along the tree of other objects according to the inclusion of cpusets, to eventually be added as a child of the smallest object including this object\&. |
| 76 |
|
| 77 |
.PP |
| 78 |
If the cpuset is empty, the type of the object (and maybe some attributes) must be enough to find where to insert the object\&. This is especially true for NUMA nodes with memory and no CPUs\&. |
| 79 |
|
| 80 |
.PP |
| 81 |
The given object should not have children\&. |
| 82 |
|
| 83 |
.PP |
| 84 |
This shall only be called before levels are built\&. |
| 85 |
|
| 86 |
.PP |
| 87 |
The caller should check whether the object type is filtered-out before calling this function\&. |
| 88 |
|
| 89 |
.PP |
| 90 |
The topology cpuset/nodesets will be enlarged to include the object sets\&. |
| 91 |
|
| 92 |
.PP |
| 93 |
\fRreason\fP is a unique string identifying where and why this insertion call was performed (it will be displayed in case of internal insertion error)\&. |
| 94 |
|
| 95 |
.PP |
| 96 |
Returns the object on success\&. Returns NULL and frees obj on error\&. Returns another object and frees obj if it was merged with an identical pre-existing object\&. |
| 97 |
.SS "\fBhwloc_obj_t\fP hwloc_alloc_setup_object (\fBhwloc_topology_t\fP topology, \fBhwloc_obj_type_t\fP type, unsigned os_index)" |
| 98 |
|
| 99 |
.PP |
| 100 |
Allocate and initialize an object of the given type and physical index\&. If \fRos_index\fP is unknown or irrelevant, use \fRHWLOC_UNKNOWN_INDEX\fP\&. |
| 101 |
.SS "int hwloc_hide_errors (void )" |
| 102 |
|
| 103 |
.PP |
| 104 |
Check whether error messages are hidden\&. Callers should print critical error messages (e\&.g\&. invalid hw topo info, invalid config) only if this function returns strictly less than 2\&. |
| 105 |
|
| 106 |
.PP |
| 107 |
Callers should print non-critical error messages (e\&.g\&. failure to initialize CUDA) if this function returns 0\&. |
| 108 |
|
| 109 |
.PP |
| 110 |
This function return 1 by default (show critical only), 0 in lstopo (show all), or anything set in HWLOC_HIDE_ERRORS in the environment\&. |
| 111 |
|
| 112 |
.PP |
| 113 |
Use macros \fBHWLOC_SHOW_CRITICAL_ERRORS()\fP and \fBHWLOC_SHOW_ALL_ERRORS()\fP for clarity\&. |
| 114 |
.SS "void hwloc_insert_object_by_parent (struct hwloc_topology * topology, \fBhwloc_obj_t\fP parent, \fBhwloc_obj_t\fP obj)" |
| 115 |
|
| 116 |
.PP |
| 117 |
Insert an object somewhere in the topology\&. It is added as the last child of the given parent\&. The cpuset is completely ignored, so strange objects such as I/O devices should preferably be inserted with this\&. |
| 118 |
|
| 119 |
.PP |
| 120 |
When used for "normal" children with cpusets (when importing from XML when duplicating a topology), the caller should make sure that: |
| 121 |
.IP "\(bu" 2 |
| 122 |
children are inserted in order, |
| 123 |
.IP "\(bu" 2 |
| 124 |
children cpusets do not intersect\&. |
| 125 |
.PP |
| 126 |
|
| 127 |
.PP |
| 128 |
The given object may have normal, I/O or Misc children, as long as they are in order as well\&. These children must have valid parent and next_sibling pointers\&. |
| 129 |
|
| 130 |
.PP |
| 131 |
The caller should check whether the object type is filtered-out before calling this function\&. |
| 132 |
.SS "int hwloc_obj_add_children_sets (\fBhwloc_obj_t\fP obj)" |
| 133 |
|
| 134 |
.PP |
| 135 |
Setup object cpusets/nodesets by OR'ing its children\&. Used when adding an object late in the topology\&. Will update the new object by OR'ing all its new children sets\&. |
| 136 |
|
| 137 |
.PP |
| 138 |
Used when PCI backend adds a hostbridge parent, when distances add a new Group, etc\&. |
| 139 |
.SS "int hwloc_topology_reconnect (\fBhwloc_topology_t\fP topology, unsigned long flags)" |
| 140 |
|
| 141 |
.PP |
| 142 |
Request a reconnection of children and levels in the topology\&. May be used by backends during discovery if they need arrays or lists of object within levels or children to be fully connected\&. |
| 143 |
|
| 144 |
.PP |
| 145 |
\fRflags\fP is currently unused, must 0\&. |
| 146 |
.SH "Author" |
| 147 |
.PP |
| 148 |
Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&. |