fabric/av: Introduce FI_SOURCE_ERR flag

include/rdma/fabric.h

@@ -146,7 +146,7 @@ typedef struct fid *fid_t;
 #define FI_DELIVERY_COMPLETE	(1ULL << 28)
 #define FI_AFFINITY		(1ULL << 29)
 
-/* fi_getinfo()-specific flags/caps */
+#define FI_SOURCE_ERR		(1ULL << 50)
 #define FI_LOCAL_COMM		(1ULL << 51)
 #define FI_REMOTE_COMM		(1ULL << 52)
 #define FI_SHARED_AV		(1ULL << 53)

man/fi_cq.3.md

@@ -353,14 +353,23 @@ the the same as the count parameter.
 
 Returned source addressing data is converted from the native address
 used by the underlying fabric into an fi_addr_t, which may be used in
-transmit operations.  Returning fi_addr_t requires that the source
-address be inserted into the address vector associated with the
-receiving endpoint.  For applications using API version 1.5 and later
-(specified through the fi_getinfo call), if the source address has not
-been inserted into the address vector, fi_cq_readfrom will return
--FI_EAVAIL.  The completion will then be reported through
-fi_cq_readerr with error code -FI_EADDRNOTAVAIL.  See fi_cq_readerr
-for details.
+transmit operations.  Typically, returning fi_addr_t requires that
+the source address be inserted into the address vector associated with the
+receiving endpoint.  For endpoints allocated using the FI_SOURCE_ERR
+capability, if the source address has not been inserted into the
+address vector, fi_cq_readfrom will return -FI_EAVAIL.  The
+completion will then be reported through fi_cq_readerr with error
+code -FI_EADDRNOTAVAIL.  See fi_cq_readerr for details.
+
+If FI_SOURCE is specified without FI_SOURCE_ERR, source addresses
+which cannot be mapped to a local fi_addr_t will be reported as
+FI_ADDR_NOTAVAIL.  The behavior is dependent on the type of address
+vector in use.  For AVs of type FI_AV_MAP, source addresses may be
+mapped directly to an fi_addr_t value, even if the source address
+were not inserted into the AV.  This allows the provider to optimize
+the reporting of the source fi_addr_t without the overhead of
+verifying whether the address is in the AV.  If full address
+validation is necessary, FI_SOURCE_ERR must be used.
 
 ## fi_cq_sread / fi_cq_sreadfrom
 
@@ -410,7 +419,7 @@ information into a printable string for debugging purposes.
 Notable completion error codes are given below.
 
 *FI_EADDRNOTAVAIL*
-: This error code is used by CQs configured with FI_SOURCE to report
+: This error code is used by CQs configured with FI_SOURCE_ERR to report
   completions for which a matching fi_addr_t source address could not
   be found.  An error code of FI_EADDRNOTAVAIL indicates that the data
   transfer was successfully received and processed, with the
@@ -437,15 +446,15 @@ of these fields are the same for all CQ entry structure formats.
 : The operation context is the application specified context value that
   was provided with an asynchronous operation.  The op_context field is
   valid for all completions.
-  
+
 *flags*
 : This specifies flags associated with the completed operation.  The
   _Completion Flags_ section below lists valid flag values.  Flags are
   set for all relevant completions.
 
 *len*
 : This len field only applies to completed receive operations (e.g. fi_recv,
-  fi_trecv, etc.).  It indicates the size of received _message_ data -- 
+  fi_trecv, etc.).  It indicates the size of received _message_ data --
   i.e. how many data bytes were placed into the associated receive buffer by
   a corresponding fi_send/fi_tsend/et al call.  If an endpoint has
   been configured with the FI_MSG_PREFIX mode, the len also reflects the size
@@ -567,7 +576,7 @@ operation.  The following completion flags are defined.
   this flag on the last message that is received into the multi-
   recv buffer, or may generate a separate completion that indicates
   that the buffer has been released.
-  
+
   Applications can distinguish between these two cases by examining
   the completion entry flags field.  If additional flags, such as
   FI_RECV, are set, the completion is associated with a received message.  In
@@ -589,8 +598,6 @@ has been set.  When enabled, only the following flags are guaranteed to
 be set in completion data when they are valid: FI_REMOTE_READ and
 FI_REMOTE_WRITE (when FI_RMA_EVENT capability bit has been set),
 FI_REMOTE_CQ_DATA, and FI_MULTI_RECV.
-
-# NOTES
 
 If a completion queue has been overrun, it will be placed into an 'overrun'
 state.  Read operations will continue to return any valid, non-corrupted

man/fi_getinfo.3.md

@@ -313,6 +313,8 @@ additional optimizations.
   require that the provider perform address translation and/or look-up
   based on data available in the underlying protocol in order to
   provide the requested data, which may adversely affect performance.
+  The performance impact may be greater for address vectors of type
+  FI_AV_TABLE.
 
 *FI_READ*
 : Indicates that the user requires an endpoint capable of initiating
@@ -384,6 +386,14 @@ additional optimizations.
   FI_LOCAL_COMM, for example NICs that lack loopback support, cannot
   be used to communicate with processes on the same system.
 
+*FI_SOURCE_ERR*
+: Must be paired with FI_SOURCE.  When specified, this requests that
+  raw source addressing data be returned as part of completion data
+  for any address that has not been inserted into the local address
+  vector.  Use of this capability may require the provider to
+  validate incoming source address data against addresses stored in
+  the local address vector, which may adversely affect performance.
+
 Capabilities may be grouped into two general categories: primary and
 secondary.  Primary capabilities must explicitly be requested by an
 application, and a provider must enable support for only those primary
@@ -398,7 +408,7 @@ FI_DIRECTED_RECV, FI_READ, FI_WRITE, FI_RECV, FI_SEND, FI_REMOTE_READ,
 and FI_REMOTE_WRITE.
 
 Secondary capabilities: FI_MULTI_RECV, FI_SOURCE, FI_RMA_EVENT, FI_SHARED_AV,
-FI_TRIGGER, FI_FENCE, FI_LOCAL_COMM, FI_REMOTE_COMM.
+FI_TRIGGER, FI_FENCE, FI_LOCAL_COMM, FI_REMOTE_COMM, FI_SOURCE_ERR.
 
 # MODE