1 /* 2 * Copyright © 2009-2018 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 * The returned buffer ends with a \0 that is included in the returned 90 * length. 91 * 92 * \p flags is a OR'ed set of ::hwloc_topology_export_xml_flags_e. 93 * 94 * \return -1 if a failure occured. 95 * 96 * \note See also hwloc_topology_set_userdata_export_callback() 97 * for exporting application-specific object userdata. 98 * 99 * \note The topology-specific userdata pointer is ignored when exporting to XML. 100 * 101 * \note Only printable characters may be exported to XML string attributes. 102 * Any other character, especially any non-ASCII character, will be silently 103 * dropped. 104 */ 105 HWLOC_DECLSPEC int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen, unsigned long flags); 106 107 /** \brief Free a buffer allocated by hwloc_topology_export_xmlbuffer() */ 108 HWLOC_DECLSPEC void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer); 109 110 /** \brief Set the application-specific callback for exporting object userdata 111 * 112 * The object userdata pointer is not exported to XML by default because hwloc 113 * does not know what it contains. 114 * 115 * This function lets applications set \p export_cb to a callback function 116 * that converts this opaque userdata into an exportable string. 117 * 118 * \p export_cb is invoked during XML export for each object whose 119 * \p userdata pointer is not \c NULL. 120 * The callback should use hwloc_export_obj_userdata() or 121 * hwloc_export_obj_userdata_base64() to actually export 122 * something to XML (possibly multiple times per object). 123 * 124 * \p export_cb may be set to \c NULL if userdata should not be exported to XML. 125 * 126 * \note The topology-specific userdata pointer is ignored when exporting to XML. 127 */ 128 HWLOC_DECLSPEC void hwloc_topology_set_userdata_export_callback(hwloc_topology_t topology, 129 void (*export_cb)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj)); 130 131 /** \brief Export some object userdata to XML 132 * 133 * This function may only be called from within the export() callback passed 134 * to hwloc_topology_set_userdata_export_callback(). 135 * It may be invoked one of multiple times to export some userdata to XML. 136 * The \p buffer content of length \p length is stored with optional name 137 * \p name. 138 * 139 * When importing this XML file, the import() callback (if set) will be 140 * called exactly as many times as hwloc_export_obj_userdata() was called 141 * during export(). It will receive the corresponding \p name, \p buffer 142 * and \p length arguments. 143 * 144 * \p reserved, \p topology and \p obj must be the first three parameters 145 * that were given to the export callback. 146 * 147 * Only printable characters may be exported to XML string attributes. 148 * If a non-printable character is passed in \p name or \p buffer, 149 * the function returns -1 with errno set to EINVAL. 150 * 151 * If exporting binary data, the application should first encode into 152 * printable characters only (or use hwloc_export_obj_userdata_base64()). 153 * It should also take care of portability issues if the export may 154 * be reimported on a different architecture. 155 */ 156 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); 157 158 /** \brief Encode and export some object userdata to XML 159 * 160 * This function is similar to hwloc_export_obj_userdata() but it encodes 161 * the input buffer into printable characters before exporting. 162 * On import, decoding is automatically performed before the data is given 163 * to the import() callback if any. 164 * 165 * This function may only be called from within the export() callback passed 166 * to hwloc_topology_set_userdata_export_callback(). 167 * 168 * The function does not take care of portability issues if the export 169 * may be reimported on a different architecture. 170 */ 171 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); 172 173 /** \brief Set the application-specific callback for importing userdata 174 * 175 * On XML import, userdata is ignored by default because hwloc does not know 176 * how to store it in memory. 177 * 178 * This function lets applications set \p import_cb to a callback function 179 * that will get the XML-stored userdata and store it in the object as expected 180 * by the application. 181 * 182 * \p import_cb is called during hwloc_topology_load() as many times as 183 * hwloc_export_obj_userdata() was called during export. The topology 184 * is not entirely setup yet. Object attributes are ready to consult, 185 * but links between objects are not. 186 * 187 * \p import_cb may be \c NULL if userdata should be ignored during import. 188 * 189 * \note \p buffer contains \p length characters followed by a null byte ('\0'). 190 * 191 * \note This function should be called before hwloc_topology_load(). 192 * 193 * \note The topology-specific userdata pointer is ignored when importing from XML. 194 */ 195 HWLOC_DECLSPEC void hwloc_topology_set_userdata_import_callback(hwloc_topology_t topology, 196 void (*import_cb)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length)); 197 198 /** @} */ 199 200 201 /** \defgroup hwlocality_syntheticexport Exporting Topologies to Synthetic 202 * @{ 203 */ 204 205 /** \brief Flags for exporting synthetic topologies. 206 * 207 * Flags to be given as a OR'ed set to hwloc_topology_export_synthetic(). 208 */ 209 enum hwloc_topology_export_synthetic_flags_e { 210 /** \brief Export extended types such as L2dcache as basic types such as Cache. 211 * 212 * This is required if loading the synthetic description with hwloc < 1.9. 213 * \hideinitializer 214 */ 215 HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_EXTENDED_TYPES = (1UL<<0), 216 217 /** \brief Do not export level attributes. 218 * 219 * Ignore level attributes such as memory/cache sizes or PU indexes. 220 * This is required if loading the synthetic description with hwloc < 1.10. 221 * \hideinitializer 222 */ 223 HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_ATTRS = (1UL<<1), 224 225 /** \brief Export the memory hierarchy as expected in hwloc 1.x. 226 * 227 * Instead of attaching memory children to levels, export single NUMA node child 228 * as normal intermediate levels, when possible. 229 * This is required if loading the synthetic description with hwloc 1.x. 230 * However this may fail if some objects have multiple local NUMA nodes. 231 * \hideinitializer 232 */ 233 HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_V1 = (1UL<<2), 234 235 /** \brief Do not export memory information. 236 * 237 * Only export the actual hierarchy of normal CPU-side objects and ignore 238 * where memory is attached. 239 * This is useful for when the hierarchy of CPUs is what really matters, 240 * but it behaves as if there was a single machine-wide NUMA node. 241 * \hideinitializer 242 */ 243 HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_IGNORE_MEMORY = (1UL<<3) 244 }; 245 246 /** \brief Export the topology as a synthetic string. 247 * 248 * At most \p buflen characters will be written in \p buffer, 249 * including the terminating \0. 250 * 251 * This exported string may be given back to hwloc_topology_set_synthetic(). 252 * 253 * \p flags is a OR'ed set of ::hwloc_topology_export_synthetic_flags_e. 254 * 255 * \return The number of characters that were written, 256 * not including the terminating \0. 257 * 258 * \return -1 if the topology could not be exported, 259 * for instance if it is not symmetric. 260 * 261 * \note I/O and Misc children are ignored, the synthetic string only 262 * describes normal children. 263 * 264 * \note A 1024-byte buffer should be large enough for exporting 265 * topologies in the vast majority of cases. 266 */ 267 HWLOC_DECLSPEC int hwloc_topology_export_synthetic(hwloc_topology_t topology, char *buffer, size_t buflen, unsigned long flags); 268 269 /** @} */ 270 271 272 273 #ifdef __cplusplus 274 } /* extern "C" */ 275 #endif 276 277 278 #endif /* HWLOC_EXPORT_H */ 279