Add core specialization plugin API web page

doc/html/Makefile.am

@@ -18,6 +18,7 @@ generated_html = \
 	cons_res_share.html \
 	contributor.html \
 	core_spec.html \
+	core_spec_plugins.html \
 	cpu_management.html \
 	cray.html \
 	crypto_plugins.html \

doc/html/Makefile.in

@@ -433,6 +433,7 @@ generated_html = \
 	cons_res_share.html \
 	contributor.html \
 	core_spec.html \
+	core_spec_plugins.html \
 	cpu_management.html \
 	cray.html \
 	crypto_plugins.html \

doc/html/core_spec_plugins.shtml

+<!--#include virtual="header.txt"-->
+
+<h1><a name="top">Core Specialization Plugin Programmer Guide</a></h1>
+
+<h2> Overview</h2>
+<p> This document describes SLURM core specialization plugins and the API that
+defines them. It is intended as a resource to programmers wishing to write
+their own SLURM core specialization plugins. This is version 100 of the API.
+
+<p>SLURM core specialization plugins must conform to the
+SLURM Plugin API with the following specifications:
+
+<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;core_spec&quot;.
+The minor type can be any suitable name for the type of core specialization
+package.
+The following core specialization plugins are included in the SLURM distribution
+<ul>
+<li><b>cray</b>&#151;Use Cray APIs to enforce core specialization.</li>
+<li><b>none</b>&#151;Can be configured to log calls to its functions, but
+otherwise does nothing.</li>
+</ul>
+<p>SLURM can be configured to use multiple core specialization plugins if desired.</p>
+
+<p><b>NOTE:</b> These functions all accept as an argument the job step's
+container ID (as set by the proctrack plugin).
+Each job step will have a different container ID.
+Since a job may execute multiple job steps sequentially and/or in parallel;
+these functions will be called once for each job step on each compute node.</p>
+
+<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 core_spec_p_set(uint64_t cont_id, uint16_t core_count)
+<p style="margin-left:.2in"><b>Description</b>:<br>
+This function is called by the slurmstepd daemon after the job step's tasks
+have been forked and exec'ed, and immediately before they are released from
+a held state.
+Note that each job step will have a different container ID.
+Note that since a job may execute multiple job steps sequentially and/or in
+parallel; this function will be called once for each job step on each compute
+node.
+<p style="margin-left:.2in"><b>Arguments</b>: <br>
+<span class="commandline">cont_id</span>
+(input) the job step's container ID as set by the proctrack plugin.<br>
+<span class="commandline">core_count</span>
+(input) number of specialized cores to be reserved for the job.<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">
+int core_spec_p_clear(uint64_t cont_id)
+<p style="margin-left:.2in"><b>Description</b>:<br>
+This function is called by the slurmstepd daemon after the job step's tasks
+have all exited.
+Note that each job step will have a different container ID.
+Note that since a job may execute multiple job steps sequentially and/or in
+parallel; this function will be called once for each job step on each compute
+node.
+<p style="margin-left:.2in"><b>Arguments</b>: <br>
+<span class="commandline">cont_id</span>
+(input) the job step's container ID as set by the proctrack plugin.<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">
+int core_spec_p_suspend(uint64_t cont_id)
+<p style="margin-left:.2in"><b>Description</b>:<br>
+This function is called by the slurmstepd daemon immediately after the job
+step's tasks have all been sent a SIGSTOP signal.
+Note that each job step will have a different container ID.
+Note that since a job may execute multiple job steps sequentially and/or in
+parallel; this function will be called once for each job step on each compute
+node.
+<p style="margin-left:.2in"><b>Arguments</b>: <br>
+<span class="commandline">cont_id</span>
+(input) the job step's container ID as set by the proctrack plugin.<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">
+int core_spec_p_resume(uint64_t cont_id)
+<p style="margin-left:.2in"><b>Description</b>:<br>
+This function is called by the slurmstepd daemon immediately before the job
+step's tasks will all be sent a SIGCONT signal.
+Note that each job step will have a different container ID.
+Note that since a job may execute multiple job steps sequentially and/or in
+parallel; this function will be called once for each job step on each compute
+node.
+<p style="margin-left:.2in"><b>Arguments</b>: <br>
+<span class="commandline">cont_id</span>
+(input) the job step's container ID as set by the proctrack plugin.<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.
+
+<h2>Versioning</h2>
+<p> This document describes version 100 of the SLURM core specialization API.
+Future releases of SLURM may revise this API.
+<p class="footer"><a href="#top">top</a>
+
+<p style="text-align:center;">Last modified 6 February 2014</p>
+
+<!--#include virtual="footer.txt"-->

doc/html/documentation.shtml

@@ -97,6 +97,7 @@ Documenation for other versions of Slurm is distributed with the code</b></p>
 <li>Plugin Interface Details</li>
 <ul>
 <li><a href="authplugins.html">Authentication Plugin Programmer Guide</a></li>
+<li><a href="core_spec_plugins.html">Core Specialization Plugin Programmer Guide</a></li>
 <li><a href="crypto_plugins.html">Cryptographic Plugin Programmer Guide</a></li>
 <li><a href="ext_sensorsplugins.html">External Sensors Plugin Programmer Guide</a></li>
 <li><a href="jobacct_gatherplugins.html">Job Accounting Gather Plugin Programmer Guide</a></li>
@@ -122,6 +123,6 @@ Documenation for other versions of Slurm is distributed with the code</b></p>
 </li>
 </ul>
 
-<p style="text-align:center;">Last modified 1 November 2013</p>
+<p style="text-align:center;">Last modified 6 February 2014</p>
 
 <!--#include virtual="footer.txt"-->