[ewg] [PATCH] librdmacm: release notes

[Hefty, Sean]

Signed-off-by: Sean Hefty <sean.hefty at intel.com>
---
 rdma_cm_release_notes.txt |  117 +++++++++++++++++++++++++++++----------------
 1 files changed, 75 insertions(+), 42 deletions(-)

diff --git a/rdma_cm_release_notes.txt b/rdma_cm_release_notes.txt
index 977ebfa..07e4cab 100644
--- a/rdma_cm_release_notes.txt
+++ b/rdma_cm_release_notes.txt
@@ -1,7 +1,7 @@
 	     Open Fabrics Enterprise Distribution (OFED)
 		    RDMA CM in OFED 1.5 Release Notes
 			  
-			   December 2009
+			   July 2010
 
 
 ===============================================================================
@@ -10,8 +10,6 @@ Table of Contents
 1. Overview
 2. New Features
 3. Known Issues
-4. Fixed bugs since OFED 1.3
-5. Fixed bugs since OFED 1.4.2
 
 ===============================================================================
 1. Overview
@@ -30,32 +28,80 @@ API for data transfers.
 ===============================================================================
 2. New Features
 ===============================================================================
-for OFED 1.3:
-Added support for valgrind checks.
-
-Added quality of service support.  Quality of service (QoS) is automatically
-enabled through the use of the kernel rdma_cm, if the local subnet is
-configured for QoS.  Additionally, the librdmacm allows users to request
-a specific type of service to use when connecting through a new API.
-Support for QoS is fabric dependent, and usually configured by an
-administrator.  Details of QoS are outside the scope of this document;
-additional information may be found in subnet management (SM) documentation.
-
-Added sanity checks and fixes for maximum outstanding RDMA operations in an
-effort to detect application errors earlier in the connection process.
-
-Various documentation updates.
-
-for OFED 1.2:
-The RDMA CM now supports connected, datagram, and multicast data transfers.
-
-When used over Infiniband, the RDMA CM will make use of a local path record
-cache, if it is enabled.  On large fabrics, use of the local cache can greatly
-reduce connection time.  Use of a cache is not necessary for iWarp.
-
-Man pages have been created to describe the various interfaces and test
-programs available.  For a full list, users should refer to the rdma_cm.7 man
-page.
+for OFED 1.5.2:
+
+Several enhancements were added to librdmacm release 1.0.12 that
+are intended to simplify using RDMA devices and address scalability issues.
+These changes were in response to long standing requests to make
+connection establishment 'more like sockets'.  For full details,
+users should refer to the appropriate man pages.  Major changes include:
+
+* Support synchronous operation for library calls.  Users can control
+  whether an rdma_cm_id operates asynchronously or synchronously based on
+  the rdma_event_channel parameter.  Use of synchronous operations
+  reduces the amount of application code required to use the librdmacm
+  by eliminating the need for event processing code.
+
+  An rdma_cm_id will be marked for synchronous operation if the
+  rdma_event_channel parameter is NULL for rdma_create_id or
+  rdma_migrate_id.  Users can toggle between synchronous and
+  asynchronous operation through the rdma_migrate_id call.
+
+  Calls that operate synchronously include rdma_resolve_addr,
+  rdma_resolve_route, rdma_connect, rdma_accept, and rdma_get_request.
+  Synchronous event data is returned to the user through the
+  rdma_cm_id.
+
+* The addition of a new API: rdma_getaddrinfo.  This call is modeled
+  after getaddrinfo, but for RDMA devices and connections.  It has the
+  following notable deviations from getaddrinfo:
+
+  A source address is returned as part of the call to allow the
+  user to allocate necessary local HW resources for connections.
+
+  Optional routing information may be returned to support
+  Infiniband fabrics.  IB routing information includes necessary
+  path record data.  rdma_getaddrinfo will obtain this information
+  if IB ACM support (see below) is enabled.  The use of IB ACM
+  is not required for rdma_getaddrinfo.
+
+  rdma_getaddrinfo provides future extensions to support
+  more complex address and route resolution mechanisms, such as
+  multiple path support and failover.
+
+* Support for a new APIs: rdma_get_request, rdma_create_ep, and
+  rdma_destroy_ep.  rdma_get_request simplifies the passive side
+  implementation by adding synchronous support for accepting new
+  connections.  rdma_create_ep combines the functionality of
+  rdma_create_id, rdma_create_qp, rdma_resolve_addr, and rdma_resolve_route
+  in a single API that uses the output of rdma_getaddrinfo as its input.
+  
+* Support for optional parameters.  To simplify support for casual RDMA
+  developers and researchers, the librdmacm can allocate protection
+  domains, completion queues, and queue pairs on a user's behalf.
+  This simplifies the amount of information that a developer
+  must learn in order to use RDMA, plus allows the user to take
+  advantage of higher-level completion processing abstractions.
+
+  In addition to optional parameters, a user can also specify that the
+  librdmacm should automatically select usable values for RDMA read
+  operations.
+
+* Add support for IB ACM.  IB ACM (InfiniBand Assistant for Communication
+  Management) defines a socket based protocol to an IB address and route
+  resolution service.  One implementation of that service is provided
+  separately by the ibacm package, but anyone can implement the service
+  provided that they adhere to the IB ACM socket protocol.  IB ACM is an
+  experimental service targeted at increasing the scalability of applications
+  running on a large cluster.
+  
+  Use of IB ACM is not required and is controlled through the build option
+  '--with-ib_acm'.  If the librdmacm fails to contact the IB ACM service, it
+  reverts to using kernel services to resolve address and routing data.
+
+* Add RDMA helper routines.  The librdmacm provide a set of simpler verbs
+  calls for posting work requests, registering memory, and checking for
+  completions.  These calls are wrappers around libibverbs routines.
 
 ===============================================================================
 3. Known Issues
@@ -85,16 +131,3 @@ following:
      configure the IP routing tables to route multicast traffic over an RDMA
      device's IP address.
 
-
-===============================================================================
-4. Fixed bugs since OFED 1.3
-===============================================================================
-- The reject status fix has been inserted for DAPL.
-
-===============================================================================
-5. Fixed bugs since OFED 1.4.2
-===============================================================================
-- examples: print errno on failures
-- return errors from the library consistently
-- initialize correct pthread condition
-- fix race initializing library