EIC code displayed by LXR master/​include/​hwloc/​export.h	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2026-09-19 09:24:48

 /*
  * SPDX-License-Identifier: BSD-3-Clause
  * Copyright © 2009-2018 Inria.  All rights reserved.
  * Copyright © 2009-2012 Université Bordeaux
  * Copyright © 2009-2011 Cisco Systems, Inc.  All rights reserved.
  * See COPYING in top-level directory.
  */
 
 /** \file
  * \brief Exporting Topologies to XML or to Synthetic strings.
  */
 
 #ifndef HWLOC_EXPORT_H
 #define HWLOC_EXPORT_H
 
 #ifndef HWLOC_H
 #error Please include the main hwloc.h instead
 #endif
 
 
 #ifdef __cplusplus
 extern "C" {
 #elif 0
 }
 #endif
 
 
 /** \defgroup hwlocality_xmlexport Exporting Topologies to XML
  * @{
  */
 
 /** \brief Flags for exporting XML topologies.
  *
  * Flags to be given as a OR'ed set to hwloc_topology_export_xml().
  */
 enum hwloc_topology_export_xml_flags_e {
  /** \brief Export XML that is loadable by hwloc v1.x.
   * However, the export may miss some details about the topology.
   * \hideinitializer
   */
  HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 = (1UL<<0)
 };
 
 /** \brief Export the topology into an XML file.
  *
  * This file may be loaded later through hwloc_topology_set_xml().
  *
  * By default, the latest export format is used, which means older hwloc
  * releases (e.g. v1.x) will not be able to import it.
  * Exporting to v1.x specific XML format is possible using flag
  * ::HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 but it may miss some details
  * about the topology.
  * If there is any chance that the exported file may ever be imported
  * back by a process using hwloc 1.x, one should consider detecting
  * it at runtime and using the corresponding export format.
  *
  * \p flags is a OR'ed set of ::hwloc_topology_export_xml_flags_e.
  *
  * \return 0 on success, or -1 on error.
  *
  * \note See also hwloc_topology_set_userdata_export_callback()
  * for exporting application-specific object userdata.
  *
  * \note The topology-specific userdata pointer is ignored when exporting to XML.
  *
  * \note Only printable characters may be exported to XML string attributes.
  * Any other character, especially any non-ASCII character, will be silently
  * dropped.
  *
  * \note If \p name is "-", the XML output is sent to the standard output.
  */
 HWLOC_DECLSPEC int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath, unsigned long flags);
 
 /** \brief Export the topology into a newly-allocated XML memory buffer.
  *
  * \p xmlbuffer is allocated by the callee and should be freed with
  * hwloc_free_xmlbuffer() later in the caller.
  *
  * This memory buffer may be loaded later through hwloc_topology_set_xmlbuffer().
  *
  * By default, the latest export format is used, which means older hwloc
  * releases (e.g. v1.x) will not be able to import it.
  * Exporting to v1.x specific XML format is possible using flag
  * ::HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 but it may miss some details
  * about the topology.
  * If there is any chance that the exported buffer may ever be imported
  * back by a process using hwloc 1.x, one should consider detecting
  * it at runtime and using the corresponding export format.
  *
  * The returned buffer ends with a \0 that is included in the returned
  * length.
  *
  * \p flags is a OR'ed set of ::hwloc_topology_export_xml_flags_e.
  *
  * \return 0 on success, or -1 on error.
  *
  * \note See also hwloc_topology_set_userdata_export_callback()
  * for exporting application-specific object userdata.
  *
  * \note The topology-specific userdata pointer is ignored when exporting to XML.
  *
  * \note Only printable characters may be exported to XML string attributes.
  * Any other character, especially any non-ASCII character, will be silently
  * dropped.
  */
 HWLOC_DECLSPEC int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen, unsigned long flags);
 
 /** \brief Free a buffer allocated by hwloc_topology_export_xmlbuffer() */
 HWLOC_DECLSPEC void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer);
 
 /** \brief Set the application-specific callback for exporting object userdata
  *
  * The object userdata pointer is not exported to XML by default because hwloc
  * does not know what it contains.
  *
  * This function lets applications set \p export_cb to a callback function
  * that converts this opaque userdata into an exportable string.
  *
  * \p export_cb is invoked during XML export for each object whose
  * \p userdata pointer is not \c NULL.
  * The callback should use hwloc_export_obj_userdata() or
  * hwloc_export_obj_userdata_base64() to actually export
  * something to XML (possibly multiple times per object).
  *
  * \p export_cb may be set to \c NULL if userdata should not be exported to XML.
  *
  * \note The topology-specific userdata pointer is ignored when exporting to XML.
  */
 HWLOC_DECLSPEC void hwloc_topology_set_userdata_export_callback(hwloc_topology_t topology,
                                 void (*export_cb)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj));
 
 /** \brief Export some object userdata to XML
  *
  * This function may only be called from within the export() callback passed
  * to hwloc_topology_set_userdata_export_callback().
  * It may be invoked one of multiple times to export some userdata to XML.
  * The \p buffer content of length \p length is stored with optional name
  * \p name.
  *
  * When importing this XML file, the import() callback (if set) will be
  * called exactly as many times as hwloc_export_obj_userdata() was called
  * during export(). It will receive the corresponding \p name, \p buffer
  * and \p length arguments.
  *
  * \p reserved, \p topology and \p obj must be the first three parameters
  * that were given to the export callback.
  *
  * Only printable characters may be exported to XML string attributes.
  *
  * If exporting binary data, the application should first encode into
  * printable characters only (or use hwloc_export_obj_userdata_base64()).
  * It should also take care of portability issues if the export may
  * be reimported on a different architecture.
  *
  * \return 0 on success.
  * \return -1 with errno set to \c EINVAL if a non-printable character is
  * passed in \p name or \b buffer.
  */
 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);
 
 /** \brief Encode and export some object userdata to XML
  *
  * This function is similar to hwloc_export_obj_userdata() but it encodes
  * the input buffer into printable characters before exporting.
  * On import, decoding is automatically performed before the data is given
  * to the import() callback if any.
  *
  * This function may only be called from within the export() callback passed
  * to hwloc_topology_set_userdata_export_callback().
  *
  * The name must be made of printable characters for export to XML string attributes.
  *
  * The function does not take care of portability issues if the export
  * may be reimported on a different architecture.
  *
  * \return 0 on success.
  * \return -1 with errno set to \c EINVAL if a non-printable character is
  * passed in \p name.
  */
 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);
 
 /** \brief Set the application-specific callback for importing userdata
  *
  * On XML import, userdata is ignored by default because hwloc does not know
  * how to store it in memory.
  *
  * This function lets applications set \p import_cb to a callback function
  * that will get the XML-stored userdata and store it in the object as expected
  * by the application.
  *
  * \p import_cb is called during hwloc_topology_load() as many times as
  * hwloc_export_obj_userdata() was called during export. The topology
  * is not entirely setup yet. Object attributes are ready to consult,
  * but links between objects are not.
  *
  * \p import_cb may be \c NULL if userdata should be ignored during import.
  *
  * \note \p buffer contains \p length characters followed by a null byte ('\0').
  *
  * \note This function should be called before hwloc_topology_load().
  *
  * \note The topology-specific userdata pointer is ignored when importing from XML.
  */
 HWLOC_DECLSPEC void hwloc_topology_set_userdata_import_callback(hwloc_topology_t topology,
                                 void (*import_cb)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length));
 
 /** @} */
 
 
 /** \defgroup hwlocality_syntheticexport Exporting Topologies to Synthetic
  * @{
  */
 
 /** \brief Flags for exporting synthetic topologies.
  *
  * Flags to be given as a OR'ed set to hwloc_topology_export_synthetic().
  */
 enum hwloc_topology_export_synthetic_flags_e {
  /** \brief Export extended types such as L2dcache as basic types such as Cache.
   *
   * This is required if loading the synthetic description with hwloc < 1.9.
   * \hideinitializer
   */
  HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_EXTENDED_TYPES = (1UL<<0),
 
  /** \brief Do not export level attributes.
   *
   * Ignore level attributes such as memory/cache sizes or PU indexes.
   * This is required if loading the synthetic description with hwloc < 1.10.
   * \hideinitializer
   */
  HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_ATTRS = (1UL<<1),
 
  /** \brief Export the memory hierarchy as expected in hwloc 1.x.
   *
   * Instead of attaching memory children to levels, export single NUMA node child
   * as normal intermediate levels, when possible.
   * This is required if loading the synthetic description with hwloc 1.x.
   * However this may fail if some objects have multiple local NUMA nodes.
   * \hideinitializer
   */
  HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_V1 = (1UL<<2),
 
  /** \brief Do not export memory information.
   *
   * Only export the actual hierarchy of normal CPU-side objects and ignore
   * where memory is attached.
   * This is useful for when the hierarchy of CPUs is what really matters,
   * but it behaves as if there was a single machine-wide NUMA node.
   * \hideinitializer
   */
  HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_IGNORE_MEMORY = (1UL<<3)
 };
 
 /** \brief Export the topology as a synthetic string.
  *
  * At most \p buflen characters will be written in \p buffer,
  * including the terminating \0.
  *
  * This exported string may be given back to hwloc_topology_set_synthetic().
  *
  * \p flags is a OR'ed set of ::hwloc_topology_export_synthetic_flags_e.
  *
  * \return The number of characters that were written,
  * not including the terminating \0.
  *
  * \return -1 if the topology could not be exported,
  * for instance if it is not symmetric.
  *
  * \note I/O and Misc children are ignored, the synthetic string only
  * describes normal children.
  *
  * \note A 1024-byte buffer should be large enough for exporting
  * topologies in the vast majority of cases.
  */
   HWLOC_DECLSPEC int hwloc_topology_export_synthetic(hwloc_topology_t topology, char *buffer, size_t buflen, unsigned long flags);
 
 /** @} */
 
 
 
 #ifdef __cplusplus
 } /* extern "C" */
 #endif
 
 
 #endif /* HWLOC_EXPORT_H */

This page was automatically generated by the 2.3.7 LXR engine. The LXR team