[openib-general] [PATCH] osm: fat-tree documentation

[Yevgeny Kliteynik]

Hi Hal.

Added fat-tree routing details and some cosmetics in the txt files.

--
Yevgeny

Signed-off-by: Yevgeny Kliteynik <kliteyn at dev.mellanox.co.il>
---
 osm/doc/current-routing.txt |   57 ++++++++++++++++++++++++++++++++++++++----
 osm/doc/modular-routing.txt |    4 +-
 2 files changed, 53 insertions(+), 8 deletions(-)

diff --git a/osm/doc/current-routing.txt b/osm/doc/current-routing.txt
index e58ae1f..da050c6 100644
--- a/osm/doc/current-routing.txt
+++ b/osm/doc/current-routing.txt
@@ -1,5 +1,5 @@
 Current OpenSM Routing
-12/20/06
+12/27/06
 
 OpenSM offers three routing engines:
 
@@ -11,11 +11,10 @@ node, but it is constrained to ranking r
 if the subnet is not a pure Fat Tree, and deadlock may occur due to a 
 loop in the subnet.
 
-3.  Fat Tree Unicast routing algorithm - this algorithm optimizes routing
-for congestion-free "shift" communication pattern. 
-It should be chosen if a subnet is a symmetrical Fat Trees of various types,
-not just K-ary-N-Trees: non-constant K, not fully staffed, any CBB ratio.
-Similar to UPDN, Fat Tree routing is constrained to ranking rules.
+3.  Fat-tree Unicast routing algorithm - this algorithm optimizes routing
+Of fat-trees for congestion-free "shift" communication pattern. 
+It should be chosen if a subnet is a symmetrical fat-tree. 
+Similar to UPDN, Fat-tree routing is credit-loop-free.
 
 OpenSM now also offers a file method which can load routes from a table. See 
 modular-routing.txt for more information on this.
@@ -73,6 +72,7 @@ switches will be skipped. Multicast is n
 
 
 Min Hop Algorithm
+-----------------
 
 The Min Hop algorithm is invoked when neither UPDN or the file method are
 specified.
@@ -91,6 +91,9 @@ port GUID. The latter is supplied by:
 LMC awareness routes based on (remote) system or switch basis.
 
 
+UPDN Routing Algorithm
+----------------------
+
 Purpose of UPDN Algorithm
 
 The UPDN algorithm is designed to prevent deadlocks from occurring in loops 
@@ -151,3 +154,45 @@ To learn more about deadlock-free routin
 "Deadlock Free Message Routing in Multiprocessor Interconnection Networks" 
 by William J Dally and Charles L Seitz (1985).
 
+
+Fat-tree Routing Algorithm
+--------------------------
+
+Purpose:
+
+The fat-tree algorithm optimizes routing for "shift" communication pattern. 
+It should be chosen if a subnet is a symmetrical fat-tree of various types.
+It supports not just K-ary-N-Trees, by handling for non-constant K, 
+cases where not all leafs (HCAs) are present, any CBB ratio.
+As in UPDN, fat-tree also prevents credit-loop-deadlocks.
+Fat-tree algorithm supports topologies that comply with the following rules:
+  - Tree rank should be between two and eight (inclusively)
+  - Switches of the same rank should have the same number
+    of UP-going port groups*, unless they are root switches,
+    in which case the shouldn't have UP-going ports at all.
+  - Switches of the same rank should have the same number
+    of DOWN-going port groups, unless they are leaf switches.
+  - Switches of the same rank should have the same number
+    of ports in each UP-going port group.
+  - Switches of the same rank should have the same number
+    of ports in each DOWN-going port group.
+*ports that are connected to the same remote switch are referenced as 'port group'. 
+
+Note that although fat-tree algorithm supports trees with non-integer CBB 
+ratio, the routing will not be as balanced as in case of integer CBB ratio.
+In addition to this, although the algorithm allows leaf switches to have any 
+number of HCAs, the closer the tree to be fully populated, the more effective
+the "shift" communication pattern will be.
+
+The algorithm also dumps HCA ordering file (osm-ftree-ca-order.dump) in the
+same directory where the OpenSM log resides. This ordering file provides the 
+HCA order that may be used to create efficient communication pattern, that
+will match the routing tables.
+
+
+Usage:
+
+Activation through OpenSM
+
+Use '-R ftree' option to activate the fat-tree algorithm.
+
diff --git a/osm/doc/modular-routing.txt b/osm/doc/modular-routing.txt
index 3708e1b..86677d0 100644
--- a/osm/doc/modular-routing.txt
+++ b/osm/doc/modular-routing.txt
@@ -6,8 +6,8 @@ for ease of "plugging" new routing modul
 Currently, only unicast callbacks are supported. Multicast
 can be added later.
 
-One existing routing module is up-down "updn", which may be
-activate with '-R updn' option (instead of old '-u').
+One of existing routing modules is up-down "updn", which may
+be activate with '-R updn' option (instead of old '-u').
 
 General usage is:
 $ opensm -R 'module-name'
-- 
1.4.4.1.GIT