Add gres plugin programmer guide

doc/html/Makefile.am

@@ -19,6 +19,7 @@ generated_html = \
 	faq.html \
 	gang_scheduling.html \
 	gres.html \
+	gres_plugins.html \
 	help.html \
 	high_throughput.html \
 	ibm.html \

doc/html/Makefile.in

@@ -313,6 +313,7 @@ generated_html = \
 	faq.html \
 	gang_scheduling.html \
 	gres.html \
+	gres_plugins.html \
 	help.html \
 	high_throughput.html \
 	ibm.html \

doc/html/documentation.shtml

@@ -66,6 +66,7 @@ Also see <a href="publications.html">Publications and Presentations</a>.
 <li><a href="crypto_plugins.html">Cryptographic Plugin Programmer Guide</a></li>
 <li><a href="jobacct_gatherplugins.html">Job Accounting Gather Plugin Programmer Guide</a></li>
 <li><a href="accounting_storageplugins.html">Accounting Storage Plugin Programmer Guide</a></li>
+<li><a href="gres_plugins.html">Generic Resources (GRES) Plugin Programmer Guide</a></li>
 <li><a href="checkpoint_plugins.html">Job Checkpoint Plugin Programmer Guide</a></li>
 <li><a href="jobcompplugins.html">Job Completion Logging Plugin Programmer Guide</a></li>
 <li><a href="job_submit_plugins.html">Job Submission Plugin Programmer Guide</a></li>
@@ -81,6 +82,6 @@ Also see <a href="publications.html">Publications and Presentations</a>.
 </li>
 </ul>
 
-<p style="text-align:center;">Last modified 4 June 2010</p>
+<p style="text-align:center;">Last modified 27 August 2010</p>
 
 <!--#include virtual="footer.txt"-->

doc/html/gres_plugins.shtml

+<!--#include virtual="header.txt"-->
+
+<h1><a name="top">SLURM Generic Resource (GRES) Plugin API</a></h1>
+
+<h2> Overview</h2>
+<p> This document describes SLURM generic resource plugins and the API that
+defines them. It is intended as a resource to programmers wishing to write
+their own SLURM job submit plugins. This is version 100 of the API.
+
+<p>SLURM generic resource plugins must conform to the
+SLURM Plugin API with the following specifications:
+
+<p><span class="commandline">const char
+gres_name[]="<i>gres_name</i>"</span><br>
+<p style="margin-left:.2in">
+The <i>gres_name</i> should matc <i>minor</i> in <i>plugin_version</i>
+described below.</p>
+
+<p><span class="commandline">const char
+plugin_name[]="<i>full&nbsp;text&nbsp;name</i>"</span>
+<p style="margin-left:.2in">
+A free-formatted ASCII text string that identifies the plugin.
+
+<p><span class="commandline">const char
+plugin_type[]="<i>major/minor</i>"</span><br>
+<p style="margin-left:.2in">
+The major type must be &quot;gres.&quot;
+The minor type can be any suitable name
+for the type of accounting package.</p>
+
+<p><span class="commandline">const uint32_t
+plugin_version="<i>version_number</i>"</span><br>
+<p style="margin-left:.2in">
+The version number should be 100.</p>
+
+<p>We include samples in the SLURM distribution for
+<ul>
+<li><b>gpu</b>&#151;Manage GPUs (Graphics Processing Units).
+<li><b>nic</b>&#151;Manage NICs (Network Interface Cards, this plugin does
+nothing today).
+</ul>
+
+<p class="footer"><a href="#top">top</a>
+
+<h2>API Functions</h2>
+<p>All of the following functions are required. Functions which are not
+implemented must be stubbed.
+
+<p class="commandline">
+int node_config_load(List gres_conf_list)
+<p style="margin-left:.2in"><b>Description</b>:<br>
+This function is called by the <i>slurmd</i> daemon after the <i>slurm.conf</i>
+and <i>gres.conf</i> files have been read.
+It can be used to validate the configuration by testing the
+actual hardware resources available or just confirm that an entry for the
+resource was included in the <i>gres.conf</i> file.
+<p style="margin-left:.2in"><b>Arguments</b>: <br>
+<span class="commandline">gres_conf_list</span>
+(input/output) a list of configuration records generated by reading the
+<i>slurm.conf</i> and <i>gres.conf</i> files<br>
+<p style="margin-left:.2in"><b>Returns</b>: <br>
+<span class="commandline">SLURM_SUCCESS</span> on success, or<br>
+<span class="commandline">SLURM_ERROR</span> on failure.
+
+<p class="commandline">
+void job_set_env(char ***job_env_ptr, void *gres_ptr)
+<p style="margin-left:.2in"><b>Description</b>:<br>
+This function is called by the <i>slurmd</i> daemon after the getting a job
+credential and can be used to set environment variables for the job based
+upon GRES state information in that credential.
+<p style="margin-left:.2in"><b>Arguments</b>: <br>
+<span class="commandline">job_env_ptr</span>
+(input/output) pointer to the job's environment variable structure.<br>
+<span class="commandline">gres_ptr</span>
+(input) pointer to the job's GRES allocation information.<br>
+
+<p class="commandline">
+void step_set_env(char ***job_env_ptr, void *gres_ptr)
+<p style="margin-left:.2in"><b>Description</b>:<br>
+This function is called by the <i>slurmd</i> daemon after the getting a job
+step credential and can be used to set environment variables for the job step
+based upon GRES state information in that credential.
+<p style="margin-left:.2in"><b>Arguments</b>: <br>
+<span class="commandline">job_env_ptr</span>
+(input/output) pointer to the job step's environment variable structure.<br>
+<span class="commandline">gres_ptr</span>
+(input) pointer to the step's GRES allocation information.<br>
+
+<h2>Versioning</h2>
+<p> This document describes version 100 of the SLURM Generic Resource API.
+Future releases of SLURM may revise this API.
+<p class="footer"><a href="#top">top</a>
+
+<p style="text-align:center;">Last modified 27 August 2010</p>
+
+<!--#include virtual="footer.txt"-->