Debian Codegraph @

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

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