1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Hardware Locality (hwloc): Importing and exporting topologies from/to XML files</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Hardware Locality (hwloc)
 <span id="projectnumber">2.4.1</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',false,false,'search.php','Search');
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Importing and exporting topologies from/to XML files </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>
<div class="section">
</p>
<p>hwloc offers the ability to export topologies to XML files and reload them later. This is for instance useful for loading topologies faster (see <a class="el" href="a00400.html#faq_xml">I do not want hwloc to rediscover my enormous machine topology every time I rerun a process</a>), manipulating other nodes' topology, or avoiding the need for privileged processes (see <a class="el" href="a00400.html#faq_privileged">Does hwloc require privileged access?</a>).</p>
<p>Topologies may be exported to XML files thanks to <a class="el" href="a00212.html#ga333f79975b4eeb28a3d8fad3373583ce" title="Export the topology into an XML file.">hwloc_topology_export_xml()</a>, or to a XML memory buffer with <a class="el" href="a00212.html#gad33b7f7c11db10459505a3b1634fd3f1" title="Export the topology into a newly-allocated XML memory buffer.">hwloc_topology_export_xmlbuffer()</a>. The lstopo program can also serve as a XML topology export tool.</p>
<p>XML topologies may then be reloaded later with <a class="el" href="a00198.html#ga879439b7ee99407ee911b3ac64e9a25e" title="Enable XML-file based topology.">hwloc_topology_set_xml()</a> and <a class="el" href="a00198.html#ga2745616b65595e1c1e579ecc7e461fa8" title="Enable XML based topology using a memory buffer (instead of a file, as with hwloc_topology_set_xml())...">hwloc_topology_set_xmlbuffer()</a>. The HWLOC_XMLFILE environment variable also tells hwloc to load the topology from the given XML file (see <a class="el" href="a00388.html">Environment Variables</a>).</p>
<dl class="section note"><dt>Note</dt><dd>Loading XML topologies disables binding because the loaded topology may not correspond to the physical machine that loads it. This behavior may be reverted by asserting that loaded file really matches the underlying system with the HWLOC_THISSYSTEM environment variable or the <a class="el" href="a00199.html#ggada025d3ec20b4b420f8038d23d6e7bdea6ecb6abc6a0bb75e81564f8bca85783b" title="Assume that the selected backend provides the topology for the system on which we are running.">HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM</a> topology flag.</dd>
<dd>
The topology flag <a class="el" href="a00199.html#ggada025d3ec20b4b420f8038d23d6e7bdea1b66bbd66e900e5c837f71defb32ad89" title="Get the set of allowed resources from the local operating system even if the topology was loaded from...">HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES</a> may be used to load a XML topology that contains the entire machine and restrict it to the part that is actually available to the current process (e.g. when Linux Cgroup/Cpuset are used to restrict the set of resources).</dd>
<dd>
hwloc also offers the ability to export/import <a class="el" href="a00231.html">Topology differences</a>.</dd>
<dd>
XML topology files are not localized. They use a dot as a decimal separator. Therefore any exported topology can be reloaded on any other machine without requiring to change the locale.</dd>
<dd>
XML exports contain all details about the platform. It means that two very similar nodes still have different XML exports (e.g. some serial numbers or MAC addresses are different). If a less precise exporting/importing is required, one may want to look at <a class="el" href="a00395.html">Synthetic topologies</a> instead.</dd></dl>
<p>
</div><div class="section" id="xml_backends">
</p>
<h1><a class="anchor" id="xml_backends"></a>
libxml2 and minimalistic XML backends</h1>
<p>hwloc offers two backends for importing/exporting XML.</p>
<p>First, it can use the libxml2 library for importing/exporting XML files. It features full XML support, for instance when those files have to be manipulated by non-hwloc software (e.g. a XSLT parser). The libxml2 backend is enabled by default if libxml2 development headers are available (the relevant development package is usually <code>libxml2-devel</code> or <code>libxml2-dev</code>).</p>
<p>If libxml2 is not available at configure time, or if <code>--disable-libxml2</code> is passed, hwloc falls back to a custom backend. Contrary to the aforementioned full XML backend with libxml2, this minimalistic XML backend cannot be guaranteed to work with external programs. It should only be assumed to be compatible with the same hwloc release (even if using the libxml2 backend). Its advantage is, however, to always be available without requiring any external dependency.</p>
<p>If libxml2 is available but the core hwloc library should not directly depend on it, the libxml2 support may be built as a dynamicall-loaded plugin. One should pass <code>--enable-plugins</code> to enable plugin support (when supported) and build as plugins all component that support it. Or pass <code>--enable-plugins=xml_libxml</code> to only build this libxml2 support as a plugin.</p>
<p>
</div><div class="section" id="xml_errors">
</p>
<h1><a class="anchor" id="xml_errors"></a>
XML import error management</h1>
<p>Importing XML files can fail at least because of file access errors, invalid XML syntax, non-hwloc-valid XML contents, or incompatibilities between hwloc releases (see <a class="el" href="a00400.html#faq_version_xml">Are XML topology files compatible between hwloc releases?</a>).</p>
<p>Both backend cannot detect all these errors when the input XML file or buffer is selected (when <a class="el" href="a00198.html#ga879439b7ee99407ee911b3ac64e9a25e" title="Enable XML-file based topology.">hwloc_topology_set_xml()</a> or <a class="el" href="a00198.html#ga2745616b65595e1c1e579ecc7e461fa8" title="Enable XML based topology using a memory buffer (instead of a file, as with hwloc_topology_set_xml())...">hwloc_topology_set_xmlbuffer()</a> is called). Some errors such non-hwloc-valid contents can only be detected later when loading the topology with <a class="el" href="a00192.html#gabdf58d87ad77f6615fccdfe0535ff826" title="Build the actual topology.">hwloc_topology_load()</a>.</p>
<p>It is therefore strongly recommended to check the return value of both <a class="el" href="a00198.html#ga879439b7ee99407ee911b3ac64e9a25e" title="Enable XML-file based topology.">hwloc_topology_set_xml()</a> (or <a class="el" href="a00198.html#ga2745616b65595e1c1e579ecc7e461fa8" title="Enable XML based topology using a memory buffer (instead of a file, as with hwloc_topology_set_xml())...">hwloc_topology_set_xmlbuffer()</a>) and <a class="el" href="a00192.html#gabdf58d87ad77f6615fccdfe0535ff826" title="Build the actual topology.">hwloc_topology_load()</a> to handle all these errors. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1
</small></address>
</body>
</html>
|
