1 /*
2 * Copyright © 2009-2017 Inria. All rights reserved.
3 * Copyright © 2009-2012 Université Bordeaux
4 * Copyright © 2009-2011 Cisco Systems, Inc. All rights reserved.
5 * See COPYING in top-level directory.
6 */
7
8 /** \file
9 * \brief Exporting Topologies to XML or to Synthetic strings.
10 */
11
12 #ifndef HWLOC_EXPORT_H
13 #define HWLOC_EXPORT_H
14
15 #ifndef HWLOC_H
16 #error Please include the main hwloc.h instead
17 #endif
18
19
20 #ifdef __cplusplus
21 extern "C" {
22 #elif 0
23 }
24 #endif
25
26
27 /** \defgroup hwlocality_xmlexport Exporting Topologies to XML
28 * @{
29 */
30
31 /** \brief Flags for exporting XML topologies.
32 *
33 * Flags to be given as a OR'ed set to hwloc_topology_export_xml().
34 */
35 enum hwloc_topology_export_xml_flags_e {
36 /** \brief Export XML that is loadable by hwloc v1.x.
37 * However, the export may miss some details about the topology.
38 * \hideinitializer
39 */
40 HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 = (1UL<<0)
41 };
42
43 /** \brief Export the topology into an XML file.
44 *
45 * This file may be loaded later through hwloc_topology_set_xml().
46 *
47 * By default, the latest export format is used, which means older hwloc
48 * releases (e.g. v1.x) will not be able to import it.
49 * Exporting to v1.x specific XML format is possible using flag
50 * ::HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 but it may miss some details
51 * about the topology.
52 * If there is any chance that the exported file may ever be imported
53 * back by a process using hwloc 1.x, one should consider detecting
54 * it at runtime and using the corresponding export format.
55 *
56 * \p flags is a OR'ed set of ::hwloc_topology_export_xml_flags_e.
57 *
58 * \return -1 if a failure occured.
59 *
60 * \note See also hwloc_topology_set_userdata_export_callback()
61 * for exporting application-specific object userdata.
62 *
63 * \note The topology-specific userdata pointer is ignored when exporting to XML.
64 *
65 * \note Only printable characters may be exported to XML string attributes.
66 * Any other character, especially any non-ASCII character, will be silently
67 * dropped.
68 *
69 * \note If \p name is "-", the XML output is sent to the standard output.
70 */
71 HWLOC_DECLSPEC int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath, unsigned long flags);
72
73 /** \brief Export the topology into a newly-allocated XML memory buffer.
74 *
75 * \p xmlbuffer is allocated by the callee and should be freed with
76 * hwloc_free_xmlbuffer() later in the caller.
77 *
78 * This memory buffer may be loaded later through hwloc_topology_set_xmlbuffer().
79 *
80 * By default, the latest export format is used, which means older hwloc
81 * releases (e.g. v1.x) will not be able to import it.
82 * Exporting to v1.x specific XML format is possible using flag
83 * ::HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 but it may miss some details
84 * about the topology.
85 * If there is any chance that the exported buffer may ever be imported
86 * back by a process using hwloc 1.x, one should consider detecting
87 * it at runtime and using the corresponding export format.
88 *
89 * \p flags is a OR'ed set of ::hwloc_topology_export_xml_flags_e.
90 *
91 * \return -1 if a failure occured.
92 *
93 * \note See also hwloc_topology_set_userdata_export_callback()
94 * for exporting application-specific object userdata.
95 *
96 * \note The topology-specific userdata pointer is ignored when exporting to XML.
97 *
98 * \note Only printable characters may be exported to XML string attributes.
99 * Any other character, especially any non-ASCII character, will be silently
100 * dropped.
101 */
102 HWLOC_DECLSPEC int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen, unsigned long flags);
103
104 /** \brief Free a buffer allocated by hwloc_topology_export_xmlbuffer() */
105 HWLOC_DECLSPEC void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer);
106
107 /** \brief Set the application-specific callback for exporting object userdata
108 *
109 * The object userdata pointer is not exported to XML by default because hwloc
110 * does not know what it contains.
111 *
112 * This function lets applications set \p export_cb to a callback function
113 * that converts this opaque userdata into an exportable string.
114 *
115 * \p export_cb is invoked during XML export for each object whose
116 * \p userdata pointer is not \c NULL.
117 * The callback should use hwloc_export_obj_userdata() or
118 * hwloc_export_obj_userdata_base64() to actually export
119 * something to XML (possibly multiple times per object).
120 *
121 * \p export_cb may be set to \c NULL if userdata should not be exported to XML.
122 *
123 * \note The topology-specific userdata pointer is ignored when exporting to XML.
124 */
125 HWLOC_DECLSPEC void hwloc_topology_set_userdata_export_callback(hwloc_topology_t topology,
126 void (*export_cb)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj));
127
128 /** \brief Export some object userdata to XML
129 *
130 * This function may only be called from within the export() callback passed
131 * to hwloc_topology_set_userdata_export_callback().
132 * It may be invoked one of multiple times to export some userdata to XML.
133 * The \p buffer content of length \p length is stored with optional name
134 * \p name.
135 *
136 * When importing this XML file, the import() callback (if set) will be
137 * called exactly as many times as hwloc_export_obj_userdata() was called
138 * during export(). It will receive the corresponding \p name, \p buffer
139 * and \p length arguments.
140 *
141 * \p reserved, \p topology and \p obj must be the first three parameters
142 * that were given to the export callback.
143 *
144 * Only printable characters may be exported to XML string attributes.
145 * If a non-printable character is passed in \p name or \p buffer,
146 * the function returns -1 with errno set to EINVAL.
147 *
148 * If exporting binary data, the application should first encode into
149 * printable characters only (or use hwloc_export_obj_userdata_base64()).
150 * It should also take care of portability issues if the export may
151 * be reimported on a different architecture.
152 */
153 HWLOC_DECLSPEC int hwloc_export_obj_userdata(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length);
154
155 /** \brief Encode and export some object userdata to XML
156 *
157 * This function is similar to hwloc_export_obj_userdata() but it encodes
158 * the input buffer into printable characters before exporting.
159 * On import, decoding is automatically performed before the data is given
160 * to the import() callback if any.
161 *
162 * This function may only be called from within the export() callback passed
163 * to hwloc_topology_set_userdata_export_callback().
164 *
165 * The function does not take care of portability issues if the export
166 * may be reimported on a different architecture.
167 */
168 HWLOC_DECLSPEC int hwloc_export_obj_userdata_base64(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length);
169
170 /** \brief Set the application-specific callback for importing userdata
171 *
172 * On XML import, userdata is ignored by default because hwloc does not know
173 * how to store it in memory.
174 *
175 * This function lets applications set \p import_cb to a callback function
176 * that will get the XML-stored userdata and store it in the object as expected
177 * by the application.
178 *
179 * \p import_cb is called during hwloc_topology_load() as many times as
180 * hwloc_export_obj_userdata() was called during export. The topology
181 * is not entirely setup yet. Object attributes are ready to consult,
182 * but links between objects are not.
183 *
184 * \p import_cb may be \c NULL if userdata should be ignored during import.
185 *
186 * \note \p buffer contains \p length characters followed by a null byte ('\0').
187 *
188 * \note This function should be called before hwloc_topology_load().
189 *
190 * \note The topology-specific userdata pointer is ignored when importing from XML.
191 */
192 HWLOC_DECLSPEC void hwloc_topology_set_userdata_import_callback(hwloc_topology_t topology,
193 void (*import_cb)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length));
194
195 /** @} */
196
197
198 /** \defgroup hwlocality_syntheticexport Exporting Topologies to Synthetic
199 * @{
200 */
201
202 /** \brief Flags for exporting synthetic topologies.
203 *
204 * Flags to be given as a OR'ed set to hwloc_topology_export_synthetic().
205 */
206 enum hwloc_topology_export_synthetic_flags_e {
207 /** \brief Export extended types such as L2dcache as basic types such as Cache.
208 *
209 * This is required if loading the synthetic description with hwloc < 1.9.
210 * \hideinitializer
211 */
212 HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_EXTENDED_TYPES = (1UL<<0),
213
214 /** \brief Do not export level attributes.
215 *
216 * Ignore level attributes such as memory/cache sizes or PU indexes.
217 * This is required if loading the synthetic description with hwloc < 1.10.
218 * \hideinitializer
219 */
220 HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_ATTRS = (1UL<<1),
221
222 /** \brief Export the memory hierarchy as expected in hwloc 1.x.
223 *
224 * Instead of attaching memory children to levels, export single NUMA node child
225 * as normal intermediate levels, when possible.
226 * This is required if loading the synthetic description with hwloc 1.x.
227 * However this may fail if some objects have multiple local NUMA nodes.
228 * \hideinitializer
229 */
230 HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_V1 = (1UL<<2),
231
232 /** \brief Do not export memory information.
233 *
234 * Only export the actual hierarchy of normal CPU-side objects and ignore
235 * where memory is attached.
236 * This is useful for when the hierarchy of CPUs is what really matters,
237 * but it behaves as if there was a single machine-wide NUMA node.
238 * \hideinitializer
239 */
240 HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_IGNORE_MEMORY = (1UL<<3)
241 };
242
243 /** \brief Export the topology as a synthetic string.
244 *
245 * At most \p buflen characters will be written in \p buffer,
246 * including the terminating \0.
247 *
248 * This exported string may be given back to hwloc_topology_set_synthetic().
249 *
250 * \p flags is a OR'ed set of ::hwloc_topology_export_synthetic_flags_e.
251 *
252 * \return The number of characters that were written,
253 * not including the terminating \0.
254 *
255 * \return -1 if the topology could not be exported,
256 * for instance if it is not symmetric.
257 *
258 * \note I/O and Misc children are ignored, the synthetic string only
259 * describes normal children.
260 *
261 * \note A 1024-byte buffer should be large enough for exporting
262 * topologies in the vast majority of cases.
263 */
264 HWLOC_DECLSPEC int hwloc_topology_export_synthetic(hwloc_topology_t topology, char *buffer, size_t buflen, unsigned long flags);
265
266 /** @} */
267
268
269
270 #ifdef __cplusplus
271 } /* extern "C" */
272 #endif
273
274
275 #endif /* HWLOC_EXPORT_H */