| 1 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| 2 |
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US"> |
| 3 |
<head> |
| 4 |
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> |
| 5 |
<meta http-equiv="X-UA-Compatible" content="IE=11"/> |
| 6 |
<meta name="generator" content="Doxygen 1.15.0"/> |
| 7 |
<meta name="viewport" content="width=device-width, initial-scale=1"/> |
| 8 |
<title>Hardware Locality (hwloc): Components and plugins</title> |
| 9 |
<link href="tabs.css" rel="stylesheet" type="text/css"/> |
| 10 |
<script type="text/javascript" src="jquery.js"></script> |
| 11 |
<script type="text/javascript" src="dynsections.js"></script> |
| 12 |
<script type="text/javascript" src="clipboard.js"></script> |
| 13 |
<link href="doxygen.css" rel="stylesheet" type="text/css" /> |
| 14 |
</head> |
| 15 |
<body> |
| 16 |
<div id="top"><!-- do not remove this div, it is closed by doxygen! --> |
| 17 |
<div id="titlearea"> |
| 18 |
<table cellspacing="0" cellpadding="0"> |
| 19 |
<tbody> |
| 20 |
<tr id="projectrow"> |
| 21 |
<td id="projectalign"> |
| 22 |
<div id="projectname">Hardware Locality (hwloc)<span id="projectnumber"> 2.14.0</span> |
| 23 |
</div> |
| 24 |
</td> |
| 25 |
</tr> |
| 26 |
</tbody> |
| 27 |
</table> |
| 28 |
</div> |
| 29 |
<!-- end header part --> |
| 30 |
<!-- Generated by Doxygen 1.15.0 --> |
| 31 |
<script type="text/javascript"> |
| 32 |
$(function() { codefold.init(); }); |
| 33 |
</script> |
| 34 |
<script type="text/javascript" src="menudata.js"></script> |
| 35 |
<script type="text/javascript" src="menu.js"></script> |
| 36 |
<script type="text/javascript"> |
| 37 |
$(function() { |
| 38 |
initMenu('',false,false,'search.php','Search',false); |
| 39 |
}); |
| 40 |
</script> |
| 41 |
<div id="main-nav"></div> |
| 42 |
</div><!-- top --> |
| 43 |
<div id="doc-content"> |
| 44 |
<div><div class="header"> |
| 45 |
<div class="headertitle"><div class="title">Components and plugins </div></div> |
| 46 |
</div><!--header--> |
| 47 |
<div class="contents"> |
| 48 |
<div class="textblock"><p>hwloc is organized in <b>components</b> that are responsible for discovering objects. Depending on the topology configuration, some components will be used (once enabled, they create a <b>backend</b>), some will be ignored.</p> |
| 49 |
<p>The usual default is to enable the native operating system component, (e.g. <span class="tt">linux</span> or <span class="tt">solaris</span>) and the <span class="tt">pci</span> one. If available, an architecture-specific component (such as <span class="tt">x86</span>) may also improve the topology detection. Finally, some hardware-specific components (such as <span class="tt">cuda</span> or <span class="tt">rsmi</span>) may add information about GPUs, accelerators, etc.</p> |
| 50 |
<p>If a XML topology is loaded, the <span class="tt">xml</span> discovery component will be used instead of all other components.</p> |
| 51 |
<h1 class="doxsection"><a class="anchor" id="plugins_default"></a> |
| 52 |
Components enabled by default</h1> |
| 53 |
<p>The hwloc core contains a list of components sorted by priority. Each one is enabled as long as it does not conflict with the previously enabled ones. This includes native operating system components, architecture-specific ones, and if available, I/O components such as <span class="tt">pci</span>.</p> |
| 54 |
<p>Usually the native operating system component (when it exists, e.g. <span class="tt">linux</span> or <span class="tt">aix</span>) is enabled first. Then hwloc looks for an architecture specific component (e.g. <span class="tt">x86</span>). Finally there also exist a basic component (<span class="tt">no_os</span>) that just tries to discover the number of PUs in the system.</p> |
| 55 |
<p>Each component discovers as much topology information as possible. Most of them, including most native OS components, do nothing unless the topology is still empty. Some others, such as <span class="tt">x86</span> and <span class="tt">pci</span>, can complete and annotate what other backends found earlier. Discovery is performed by phases: CPUs are first discovered, then memory is attached, then PCI, etc.</p> |
| 56 |
<p>Default priorities ensure that clever components are invoked first. Native operating system components have higher priorities, and are therefore invoked first, because they likely offer very detailed topology information. If needed, it will be later extended by architecture-specific information (e.g. from the <span class="tt">x86</span> component).</p> |
| 57 |
<p>If any configuration function such as <a class="el" href="a00175.html#ga879439b7ee99407ee911b3ac64e9a25e" title="Enable XML-file based topology.">hwloc_topology_set_xml()</a> is used before loading the topology, the corresponding component is enabled first. Then, as usual, hwloc enables any other component (based on priorities) that does not conflict.</p> |
| 58 |
<p>Certain components that manage a virtual topology, for instance XML topology import or synthetic topology description, conflict with all other components. Therefore, they may only be loaded (e.g. with <span class="tt"><a class="el" href="a00175.html#ga879439b7ee99407ee911b3ac64e9a25e" title="Enable XML-file based topology.">hwloc_topology_set_xml()</a></span>) if no other component is enabled.</p> |
| 59 |
<p>The environment variable <span class="tt">HWLOC_COMPONENTS_VERBOSE</span> may be set to get verbose messages about available components (including their priority) and enabling as backends.</p> |
| 60 |
<h1 class="doxsection"><a class="anchor" id="plugins_select"></a> |
| 61 |
Selecting which components to use</h1> |
| 62 |
<p>If no topology configuration functions such as <span class="tt"><a class="el" href="a00175.html#ga4fab186bb6181a00bcf585825fddd38d" title="Enable synthetic topology.">hwloc_topology_set_synthetic()</a></span> have been called, components may be selected with environment variables such as <span class="tt">HWLOC_XMLFILE</span>, <span class="tt">HWLOC_SYNTHETIC</span>, <span class="tt">HWLOC_FSROOT</span>, or <span class="tt">HWLOC_CPUID_PATH</span> (see <a class="el" href="a00373.html#envvar_source">Environment variables for changing the source of topology information</a>).</p> |
| 63 |
<p>Finally, the environment variable <span class="tt">HWLOC_COMPONENTS</span> resets the list of selected components. If the variable is set and empty (or set to a single comma separating nothing, since some operating systems do not accept empty variables), the normal component priority order is used.</p> |
| 64 |
<p>If the variable is set to <span class="tt">x86</span> in this variable will cause the <span class="tt">x86</span> component to take precedence over any other component, including the native operating system component. It is therefore loaded first, before hwloc tries to load all remaining non-conflicting components. In this case, <span class="tt">x86</span> would take care of discovering everything it supports, instead of only completing what the native OS information. This may be useful if the native component is buggy on some platforms.</p> |
| 65 |
<p>It is possible to prevent some components from being loaded by prefixing their name with <span class="tt">-</span> in the list. For instance <span class="tt">x86,-pci</span> will load the <span class="tt">x86</span> component, then let hwloc load all the usual components except <span class="tt">pci</span>. A single component phase may also be blacklisted, for instance with <span class="tt">-linux:io</span>.</p> |
| 66 |
<p>It is possible to prevent all remaining components from being loaded by placing <span class="tt">stop</span> in the environment variable. Only the components listed before this keyword will be enabled.</p> |
| 67 |
<p><a class="el" href="a00175.html#ga9ad41adf418cee1c0ee32ba9bd4a3d36" title="Prevent a discovery component from being used for a topology.">hwloc_topology_set_components()</a> may also be used inside the program to prevent the loading of a specific component (or phases) for the target topology.</p> |
| 68 |
<h1 class="doxsection"><a class="anchor" id="plugins_load"></a> |
| 69 |
Loading components from plugins</h1> |
| 70 |
<p>Components may optionally be built as <b>plugins</b> so that the hwloc core library does not directly depend on their dependencies (for instance the <span class="tt">libpciaccess</span> library). Plugin support may be enabled with the <span class="tt">--enable-plugins</span> configure option, or with the <span class="tt">HWLOC_ENABLE_PLUGINS</span> CMake options on Windows. All components buildable as plugins will then be built as plugins. The configure option may be given a comma-separated list of component names to specify the exact list of components to build as plugins.</p> |
| 71 |
<p>Plugins are built as independent dynamic libraries that are installed in <span class="tt">$libdir/hwloc</span>. All plugins found in this directory are loaded during <span class="tt">topology_init()</span> (unless blacklisted in <span class="tt">HWLOC_PLUGINS_BLACKLIST</span>, see <a class="el" href="a00373.html#envvar_components">Environment variables for controlling components and plugins</a>). A specific list of directories (colon-separated) to scan may be specified in the <span class="tt">HWLOC_PLUGINS_PATH</span> environment variable.</p> |
| 72 |
<p>Note that loading a plugin just means that the corresponding component is registered to the hwloc core. Components are then only enabled (as a <b>backend</b>) if the topology configuration requests it, as explained in the previous sections.</p> |
| 73 |
<p>Also note that plugins should carefully be enabled and used when embedding hwloc in another project, see <a class="el" href="a00385.html">Embedding hwloc in Other Software</a> for details.</p> |
| 74 |
<h1 class="doxsection"><a class="anchor" id="plugins_list"></a> |
| 75 |
Existing components and plugins</h1> |
| 76 |
<p>All components distributed within hwloc are listed below. The list of actually available components may be listed at running with the <span class="tt">HWLOC_COMPONENTS_VERBOSE</span> environment variable (see <a class="el" href="a00373.html#envvar_verbose">Environment variables for changing the verbosity</a>).</p> |
| 77 |
<dl> |
| 78 |
<dt>linux </dt> |
| 79 |
<dd>The official component for discovering CPU, memory and I/O devices on Linux. It discovers PCI devices without the help of external libraries such as libpciaccess, but requires the pci component for adding vendor/device names to PCI objects. It also discovers many kinds of Linux-specific OS devices. </dd> |
| 80 |
<dt>aix, darwin, freebsd, hpux, netbsd, solaris, windows </dt> |
| 81 |
<dd>Each officially supported operating system has its own native component, which is statically built when supported, and which is used by default. </dd> |
| 82 |
<dt>x86 </dt> |
| 83 |
<dd>The x86 architecture (either 32 or 64 bits) has its own component that may complete or replace the previously-found CPU information. It is statically built when supported. </dd> |
| 84 |
<dt>bgq </dt> |
| 85 |
<dd>This component is specific to IBM BlueGene/Q compute node (running CNK). It is built and enabled by default when <span class="tt">--host=powerpc64-bgq-linux</span> is passed to configure (see <a class="el" href="a00386.html#faq_bgq">How do I build hwloc for BlueGene/Q?</a>). </dd> |
| 86 |
<dt>no_os </dt> |
| 87 |
<dd>A basic component that just tries to detect the number of processing units in the system. It mostly serves on operating systems that are not natively supported. It is always statically built. </dd> |
| 88 |
<dt>pci </dt> |
| 89 |
<dd>PCI object discovery uses the external libpciaccess library; see <a class="el" href="a00375.html">I/O Devices</a>. It may also annotate existing PCI devices with vendor and device names. <b>It may be built as a plugin</b>. </dd> |
| 90 |
<dt>opencl </dt> |
| 91 |
<dd>The OpenCL component creates co-processor OS device objects such as <em>opencl0d0</em> (first device of the first OpenCL platform) or <em>opencl1d3</em> (fourth device of the second platform). Only the AMD and NVIDIA OpenCL implementations currently offer locality information. <b>It may be built as a plugin</b>. </dd> |
| 92 |
<dt>rsmi </dt> |
| 93 |
<dd>This component creates GPU OS device objects such as <em>rsmi0</em> for describing AMD GPUs. <b>It may be built as a plugin</b>. </dd> |
| 94 |
<dt>levelzero </dt> |
| 95 |
<dd>This component creates co-processor OS device objects such as <em>ze0</em> for describing oneAPI Level Zero devices. It may also create sub-OS-devices such as <em>ze0.0</em> inside those devices. <b>It may be built as a plugin</b>. </dd> |
| 96 |
<dt>cuda </dt> |
| 97 |
<dd>This component creates co-processor OS device objects such as <em>cuda0</em> that correspond to NVIDIA GPUs used with CUDA library. <b>It may be built as a plugin</b>. </dd> |
| 98 |
<dt>nvml </dt> |
| 99 |
<dd>Probing the NVIDIA Management Library creates OS device objects such as <em>nvml0</em> that are useful for batch schedulers. It also detects the actual PCIe link bandwidth without depending on power management state and without requiring administrator privileges. <b>It may be built as a plugin</b>. </dd> |
| 100 |
<dt>gl </dt> |
| 101 |
<dd>Probing the NV-CONTROL X extension (NVCtrl library) creates OS device objects such as <em>:0.0</em> corresponding to NVIDIA displays. They are useful for graphical applications that need to place computation and/or data near a rendering GPU. <b>It may be built as a plugin</b>. <br /> |
| 102 |
However this code may hang when trying to connect to the X server. Hence <b>this component is disabled unless HWLOC_GL=1 is set in the environment</b>. </dd> |
| 103 |
<dt>synthetic </dt> |
| 104 |
<dd>Synthetic topology support (see <a class="el" href="a00381.html">Synthetic topologies</a>) is always built statically. </dd> |
| 105 |
<dt>xml </dt> |
| 106 |
<dd>XML topology import (see <a class="el" href="a00380.html">Importing and exporting topologies from/to XML files</a>) is always built statically. It internally uses a specific class of components for the actual XML import/export routines (see <a class="el" href="a00380.html#xml_backends">libxml2 and minimalistic XML backends</a> for details). <ul> |
| 107 |
<li> |
| 108 |
<b>xml_nolibxml</b> is a basic and hwloc-specific XML import/export. It is always statically built. </li> |
| 109 |
<li> |
| 110 |
<b>xml_libxml</b> relies on the external libxml2 library for provinding a feature-complete XML import/export. <b>It may be built as a plugin</b>. </li> |
| 111 |
</ul> |
| 112 |
</dd> |
| 113 |
<dt>fake </dt> |
| 114 |
<dd>A dummy plugin that does nothing but is used for debugging plugin support. </dd> |
| 115 |
</dl> |
| 116 |
</div></div><!-- contents --> |
| 117 |
</div><!-- PageDoc --> |
| 118 |
<!-- start footer part --> |
| 119 |
<hr class="footer"/><address class="footer"><small> |
| 120 |
Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.15.0 |
| 121 |
</small></address> |
| 122 |
</div><!-- doc-content --> |
| 123 |
</body> |
| 124 |
</html> |