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
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://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.8.8"/>
<title>Hardware Locality (hwloc): Components and plugins</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 style="padding-left: 0.5em;">
<div id="projectname">Hardware Locality (hwloc)
 <span id="projectnumber">1.10.0</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.8 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Components and plugins </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>hwloc is organized in components that are responsible for discovering objects. Depending on the topology configuration, some components will be used, some will be ignored. The usual default is to enable the native operating system component, (e.g. <code>linux</code> or <code>solaris</code>) and the <code>pci</code> miscellaneous component. If available, an architecture-specific component (such as <code>x86</code>) may also improve the topology detection.</p>
<p>If a XML topology is loaded, the <code>xml</code> discovery component will be used instead of all other components. It internally uses a specific class of components for the actual XML import/export routines (<code>xml_libxml</code> and <code>xml_nolibxml</code>) but these will not be discussed here (see <a class="el" href="a00016.html#xml_backends">libxml2 and minimalistic XML backends</a>).</p>
<h1><a class="anchor" id="plugins_default"></a>
Components enabled by default</h1>
<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 <code>pci</code>.</p>
<p>Usually the native operating system component (when it exists, e.g. <code>linux</code> or <code>aix</code>) is enabled first. Then hwloc looks for an architecture specific component (e.g. <code>x86</code>). Finally these also exist a basic component (<code>no_os</code>) that just tries to discover the number of PUs in the system.</p>
<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 <code>x86</code> and <code>pci</code>, can complete and annotate what other backends still earlier.</p>
<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 <code>x86</code> component).</p>
<p>If any configuration function such as <a class="el" href="a00077.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>
<p>Certain components that manage a virtual topology, for instance XML topology import, synthetic topology description, or custom building, conflict with all other components. Therefore, one of them may only be loaded (e.g. with <code><a class="el" href="a00077.html#ga879439b7ee99407ee911b3ac64e9a25e" title="Enable XML-file based topology. ">hwloc_topology_set_xml()</a></code>) if no other component is enabled.</p>
<p>The environment variable <code>HWLOC_COMPONENTS_VERBOSE</code> may be set to get verbose messages about component registration (including their priority) and enabling.</p>
<h1><a class="anchor" id="plugins_select"></a>
Selecting which components to use</h1>
<p>Once topology configuration functions such as <code><a class="el" href="a00077.html#gad1f15795219e2c3ca6d44ba0db604c4f" title="Prepare the topology for custom assembly. ">hwloc_topology_set_custom()</a></code> have been taken care of, the priority order of the remaining components may be changed through the <code>HWLOC_COMPONENTS</code> environment variable (component names must be separated by commas).</p>
<p>Specifying <code>x86</code> in this variable will cause the <code>x86</code> 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, <code>x86</code> 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>
<p>It is possible to prevent some components from being loaded by prefixing their name with <code>-</code> in the list. For instance <code>x86,-pci</code> will load the <code>x86</code> component, then let hwloc load all the usual components except <code>pci</code>.</p>
<p>It is possible to prevent all remaining components from being loaded by placing <code>stop</code> in the environment variable. Only the components listed before this keyword will be enabled.</p>
<p>Certain component names (<code>xml</code> and <code>synthetic</code>) accept an argument (e.g. <code>xml=file.xml</code>). These arguments behave exactly as if the corresponding string had been passed to <code><a class="el" href="a00077.html#ga879439b7ee99407ee911b3ac64e9a25e" title="Enable XML-file based topology. ">hwloc_topology_set_xml()</a></code> or <code><a class="el" href="a00077.html#ga4fab186bb6181a00bcf585825fddd38d" title="Enable synthetic topology. ">hwloc_topology_set_synthetic()</a></code>.</p>
<h1><a class="anchor" id="plugins_load"></a>
Loading components from plugins</h1>
<p>Components may optionally be built as plugins so that the hwloc core library does not directly depend on their dependencies (for instance the <code>libpciaccess</code> library). Plugin support may be enabled with the <code>–enable-plugins</code> configure option. 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>
<p>Plugins are built as independent dynamic libraries that are installed in <code>$libdir/hwloc</code>. All plugins found in this directory are loaded during <code>topology_init()</code>. A specific list of directories (colon-separated) to scan may be specified in the <code>HWLOC_PLUGINS_PATH</code> environment variable.</p>
<p>Note that loading a plugin just means that the corresponding component is registered to the hwloc core. Components are then only enabled if the topology configuration requests it, as explained in the previous sections.</p>
<p>Also note that plugins should carefully be enabled and used when embedding hwloc in another project, see <a class="el" href="a00026.html">Embedding hwloc in Other Software</a> for details.</p>
<h1><a class="anchor" id="plugins_adding"></a>
Adding new discovery components and plugins</h1>
<p>The types and functions cited below are declared in the <a class="el" href="a00071_source.html" title="Public interface for building hwloc plugins. ">hwloc/plugins.h</a> header. Components are supposed to only use hwloc public headers (<a class="el" href="a00063_source.html" title="The hwloc API. ">hwloc.h</a> and anything under the <code>include/hwloc</code> subdirectory) and nothing from the <code>include/private</code> subdirectory in the source tree.</p>
<h2><a class="anchor" id="plugins_disc_basic"></a>
Basics of discovery components</h2>
<p>Each discovery component is defined by a <code><a class="el" href="a00033.html" title="Discovery component structure. ">hwloc_disc_component</a></code> structure which contains an <code>instantiate()</code> callback. This function is invoked when this component is actually used by a topology. It fills a new <code><a class="el" href="a00029.html" title="Discovery backend structure. ">hwloc_backend</a></code> structure that usually contains <code>discover()</code> and/or <code>notify_new_object()</code> callbacks taking care of the actual topology discovery.</p>
<dl class="section note"><dt>Note</dt><dd>If two discovery components have the same name, only the highest priority one is actually made available. This offers a way for third-party plugins to override existing components.</dd></dl>
<h2><a class="anchor" id="plugins_disc_register"></a>
Registering a new discovery component</h2>
<p>Registering components to the hwloc core relies on a <code><a class="el" href="a00032.html" title="Generic component structure. ">hwloc_component</a></code> structure. Its <code>data</code> field points to the previously defined <code><a class="el" href="a00033.html" title="Discovery component structure. ">hwloc_disc_component</a></code> structure while its <code>type</code> should be HWLOC_COMPONENT_TYPE_DISC. This structure should be named <code>hwloc_<name>_component</code>.</p>
<p>The configure script should be modified to add <code><name></code> to its <code>hwloc_components</code> shell variable so that the component is actually available.</p>
<dl class="section note"><dt>Note</dt><dd>The symbol name of the <code><a class="el" href="a00032.html" title="Generic component structure. ">hwloc_component</a></code> structure is independent of the name of the discovery component mentioned in the previous section.</dd></dl>
<p>When the component is statically built inside the hwloc library, the symbol <code>hwloc_<name>_component</code> is added by configure to the <code>src/static-components.h</code>. The core then registers all components listed in this file.</p>
<p>If the new component may be built as a plugin, the configure script should also define the shell variable <code>hwloc_<name>_component_maybeplugin=1</code>. When the configure script actually enables the component as a plugin, it will set the variable <code>hwloc_<name>_component</code> to <code>plugin</code>. The build system may then use this variable to change the way the component is built. It should create a <code>hwloc_<name>.so</code> shared object. All these files are loaded in alphabetic order, and the components they contain are registered to the hwloc core.</p>
<h1><a class="anchor" id="plugins_list"></a>
Existing components and plugins</h1>
<p>All components distributed within hwloc are listed below. The list of actually available components may be listed at running with the <code>HWLOC_COMPONENTS_VERBOSE</code> environment variable (see <a class="el" href="a00006.html">Environment Variables</a>).</p>
<dl>
<dt>aix, darwin, freebsd, hpux, linux, netbsd, osf, solaris, windows </dt>
<dd>Each officially supported operating system has its own native component, which is statically built when supported, and which is used by default. </dd>
<dt>x86 </dt>
<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>
<dt>bgq </dt>
<dd>This component is specific to IBM BlueGene/Q compute node (running CNK). It is built and enabled by default when <code>–host=powerpc64-bgq-linux</code> is passed to configure (see <a class="el" href="a00028.html#faq_bgq">How do I build hwloc for BlueGene/Q?</a>). </dd>
<dt>no_os </dt>
<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>
<dt>pci </dt>
<dd>PCI object discovery uses the external pciaccess library (aka libpciaccess); see <a class="el" href="a00010.html">I/O Devices</a>. <b>It may be built as a plugin</b>. </dd>
<dt>linuxpci </dt>
<dd>This component can probe PCI devices on Linux without the help of external libraries such as libpciaccess. Its priority is lower than the pci component because it misses device names. </dd>
<dt>opencl </dt>
<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 OpenCL implementation currently offers locality information. <b>It may be built as a plugin</b>. </dd>
<dt>cuda </dt>
<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>
<dt>nvml </dt>
<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>
<dt>gl </dt>
<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>. </dd>
<dt>synthetic </dt>
<dd>Synthetic topology support (see <a class="el" href="a00018.html">Synthetic topologies</a>) is always built statically. </dd>
<dt>custom </dt>
<dd>Custom topology support (see <a class="el" href="a00012.html">Multi-node Topologies</a>) is always built statically. </dd>
<dt>xml </dt>
<dd>XML topology import (see <a class="el" href="a00016.html">Importing and exporting topologies from/to XML files</a>) is always built statically. It internally uses one of the XML backends (see <a class="el" href="a00016.html#xml_backends">libxml2 and minimalistic XML backends</a>). <ul>
<li>
<b>xml_nolibxml</b> is a basic and hwloc-specific XML import/export. It is always statically built. </li>
<li>
<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>
</ul>
</dd>
<dt>fake </dt>
<dd>A dummy plugin that does nothing but is used for debugging plugin support. </dd>
</dl>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Tue Oct 7 2014 11:56:52 for Hardware Locality (hwloc) by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.8
</small></address>
</body>
</html>
|
