- merge 0.7rc1 from b_devel to HEAD (20030612 merge point)

[fs/lustre-release.git] / lnet / ulnds / README

diff --git a/lnet/ulnds/README b/lnet/ulnds/README
new file mode 100644 (file)
index 0000000..6cb93d9
--- /dev/null
+++ b/lnet/ulnds/README
@@ -0,0 +1,53 @@
+This library implements two NAL interfaces, both running over IP.
+The first, tcpnal, creates TCP connections between participating
+processes in order to transport the portals requests. The second,
+ernal, provides a simple transport protocol which runs over
+UDP datagrams.
+
+The interface functions return both of these values in host order for
+convenience and readability. However this means that addresses
+exchanged in messages between hosts of different orderings will not
+function properly.
+
+Both NALs use the same support functions in order to schedule events
+and communicate with the generic portals implementation.
+
+            -------------------------
+            |         api           |
+            |_______________________|
+            |         lib           |
+            |_______________________|
+            | ernal  |   |tcpnal    |
+            |--------|   |----------|
+            | udpsock|   |connection|
+            |-----------------------|
+            |     timer/select      |
+            -------------------------
+
+
+  These NALs uses the framework from fdnal of a pipe between the api
+and library sides. This is wrapped up in the select on the library
+side, and blocks on the api side. Performance could be severely
+enhanced by collapsing this aritificial barrier, by using shared
+memory queues, or by wiring the api layer directly to the library.
+
+
+nid is defined as the low order 24-bits of the IP address of the
+physical node left shifted by 8 plus a virtual node number of 0
+through 255 (really only 239).  The virtual node number of a tcpnal
+application should be specified using the environment variable
+PTL_VIRTNODE.  pid is now a completely arbitrary number in the
+range of 0 to 255.  The IP interface used can be overridden by
+specifying the appropriate hostid by setting the PTL_HOSTID
+environment variable.  The value can be either dotted decimal
+(n.n.n.n) or hex starting with "0x".
+TCPNAL:
+  As the NAL needs to try to send to a particular nid/pid pair, it
+  will open up connections on demand. Because the port associated with
+  the connecting socket is different from the bound port, two
+  connections will normally be established between a pair of peers, with
+  data flowing from the anonymous connect (active) port to the advertised
+  or well-known bound (passive) port of each peer.
+
+  Should the connection fail to open, an error is reported to the
+  library component, which causes the api request to fail.