[ofa-general] [PATCH 2/2] opensm: Added documentation for external routing engines.

[Vincent Ficet]

Signed-off-by: Jean-Vincent Ficet <jean-vincent.ficet at bull.net>
---
 opensm/doc/current-routing.txt |   26 +++++++++++++++++++++++++-
 opensm/man/opensm.8.in         |    2 ++
 2 files changed, 27 insertions(+), 1 deletions(-)

diff --git a/opensm/doc/current-routing.txt b/opensm/doc/current-routing.txt
index 1302860..b0dc5bc 100644
--- a/opensm/doc/current-routing.txt
+++ b/opensm/doc/current-routing.txt
@@ -1,7 +1,7 @@
 Current OpenSM Routing
 7/9/07
 
-OpenSM offers five routing engines:
+OpenSM offers six routing engines:
 
 1.  Min Hop Algorithm - based on the minimum hops to each node where the
 path length is optimized.
@@ -28,6 +28,10 @@ two switches.  This provides deadlock free routes for hypercubes when
 the fabric is cabled as a hypercube and for meshes when cabled as a
 mesh (see details below).
 
+6. External routing engine - OpenSM provides the ability to dynamically load
+an external routing engine.
+
+
 OpenSM provides an optional unicast routing cache (enabled by -A or
 --ucast_cache options). When enabled, unicast routing cache prevents
 routing recalculation (which is a heavy task in a large cluster) when
@@ -388,3 +392,23 @@ ports, one port on one end of the cable, and the other port on the
 other end, continuing along the mesh dimension.
 
 Use '-R dor' option to activate the DOR algorithm.
+
+External routing engines
+------------------------
+
+OpenSM also offer the ability to dynamically load routing plugins.
+When OpenSM is provided with a routing engine name which is not in the
+standard list, OpenSM will try to open a library called lib'engine_name'.so.
+There are three things required to build a fonctional plugin:
+        - <opensm/osm_config.h> should be included first in the plugin to
+          ensure the right defines and struct are used.
+        - a setup function that fills a routing_engine struct with the
+          appropriate methods
+        - a osm_routing_plugin_t struct named OSM_ROUTING_PLUGIN_IMPL_NAME
+          which contains:
+                * osm_version = OSM_VERSION to make sure the plugin was build
+                  with the same OpenSM Version
+                * setup pointing to the setup function described above.
+If these requirements are filled, OpenSM will load the external plugin and
+setup the routing engine. It can then be used as any other routing engine.
+
diff --git a/opensm/man/opensm.8.in b/opensm/man/opensm.8.in
index 66d2fe6..6a6fb30 100644
--- a/opensm/man/opensm.8.in
+++ b/opensm/man/opensm.8.in
@@ -141,6 +141,8 @@ algorithm (default).  Multiple routing engines can be specified
 separated by commas so that specific ordering of routing algorithms
 will be tried if earlier routing engines fail.
 Supported engines: minhop, updn, file, ftree, lash, dor
+If the algorithm name cannot be found within the standard list,
+OpenSM will try do open an external library named lib'name'.so.
 .TP
 \fB\-\-do_mesh_analysis\fR
 This option enables additional analysis for the lash routing engine to
-- 
1.6.2.rc1.30.gd43c