Add web page to describe the topology plugin

doc/html/Makefile.am

@@ -55,6 +55,7 @@ generated_html = \
 	team.html \
 	testimonials.html \
 	topology.html \
+	topology_plugin.html \
 	troubleshoot.html
 
 html_DATA = \

doc/html/Makefile.in

@@ -309,6 +309,7 @@ generated_html = \
 	team.html \
 	testimonials.html \
 	topology.html \
+	topology_plugin.html \
 	troubleshoot.html
 
 html_DATA = \

doc/html/documentation.shtml

@@ -72,9 +72,10 @@ Also see <a href="publications.html">Publications and Presentations</a>.
 <li><a href="selectplugins.html">Resource Selection Plugin Programmer Guide</a></li>
 <li><a href="switchplugins.html">Switch (Interconnect) Plugin Programmer Guide</a></li>
 <li><a href="taskplugins.html">Task Plugin Programmer Guide</a></li>
+<li><a href="topology_plugin.html">Topology Plugin Programmer Guide</a></li>
 </li>
 </ul>
 
-<p style="text-align:center;">Last modified 9 March 2009</p>
+<p style="text-align:center;">Last modified 24 March 2009</p>
 
 <!--#include virtual="footer.txt"-->

doc/html/review_release.html

@@ -61,6 +61,7 @@
 <li><a href="https://computing-pre.llnl.gov/linux/slurm/team.html">team.html</a></li>
 <li><a href="https://computing-pre.llnl.gov/linux/slurm/testimonials.html">testimonials.html</a></li>
 <li><a href="https://computing-pre.llnl.gov/linux/slurm/topology.html">topology.html</a></li>
+<li><a href="https://computing-pre.llnl.gov/linux/slurm/topology_plugin.html">topology_plugin.html</a></li>
 <li><a href="https://computing-pre.llnl.gov/linux/slurm/troubleshoot.html">troubleshoot.html</a></li>
 </ul>
 </body>

doc/html/topology_plugin.shtml

+<!--#include virtual="header.txt"-->
+
+<h1><a name="top">SLURM Topology Plugin Programmer Guide</a></h1>
+
+<h2> Overview</h2>
+<p> This document describes SLURM topology plugin and the API that 
+defines them. 
+It is intended as a resource to programmers wishing to write their own 
+SLURM topology plugin. 
+This is version 100 of the API.</p>
+
+<p>SLURM topology plugins are SLURM plugins that implement 
+convey system topology information so that SLURM is able to 
+optimize resource allocations and minimize communication overhead. 
+The plugins must conform to the SLURM Plugin API with the following 
+specifications:</p>
+
+<p><span class="commandline">const char plugin_type[]</span><br>
+The major type must be &quot;topology.&quot; 
+The minor type specifies the type of topology mechanism. 
+We recommend, for example:</p>
+<ul>
+<li><b>3d_torus</b>&#151;Optimize placement for a three dimensional torus.</li>
+<li><b>none</b>&#151;No topology informatin.</li>
+<li><b>tree</b>&#151;Optimize placement based upon a hiearachy of network
+switches.</li>
+</ul></p>
+
+<p>The <span class="commandline">plugin_name</span> and 
+<span class="commandline">plugin_version</span> 
+symbols required by the SLURM Plugin API require no specialization for 
+topology support. 
+The actions preformed by these plugins vary widely.
+In the case of <b>3d_torus</b>, the nodes in configuration file
+are re-ordeded so that nodes which are nearby in the one-dimensional
+table are also nearby in logical three-dimensional space.
+In the case of <b>tree</b>, a tabled is built to reflect network
+topology and that table is later used by the <b>select</b> plugin
+to optimize placement.
+Note carefully, however, the versioning discussion below.</p>
+
+<h2>Data Objects</h2>
+<p>The implementation must maintain (though not necessarily directly export) an 
+enumerated <span class="commandline">errno</span> to allow SLURM to discover 
+as practically as possible the reason for any failed API call. 
+Plugin-specific enumerated integer values may be used when appropriate.
+
+<p>These values must not be used as return values in integer-valued 
+functions in the API. 
+The proper error return value from integer-valued functions is SLURM_ERROR. 
+The implementation should endeavor to provide useful and pertinent 
+information by whatever means is practical. 
+Successful API calls are not required to reset any errno to a known value. 
+However, the initial value of any errno, prior to any error condition 
+arising, should be SLURM_SUCCESS. </p>
+<p class="footer"><a href="#top">top</a></p>
+
+<h2>API Functions</h2>
+<p>The following functions must appear. 
+Functions which are not implemented should be stubbed.</p>
+
+<p class="commandline">int topo_build_config(void);</p>
+<p style="margin-left:.2in"><b>Description</b>: Generate topology information.</p>
+<p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS or 
+SLURM_ERROR on failure.</p>
+
+<h2>Versioning</h2>
+<p> This document describes version 100 of the SLURM topology API. 
+Future releases of SLURM may revise this API.</p>
+<p class="footer"><a href="#top">top</a></p>
+
+<p style="text-align:center;">Last modified 24 March 2009</p>
+
+<!--#include virtual="footer.txt"-->