Updated nroff-generated man pages

Signed-off-by: OFIWG Bot <[email protected]>

fabtests/man/man7/fabtests.7

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 2.9.2.1
 .\"
-.TH "fabtests" "7" "2024\-07\-11" "Libfabric Programmer\[cq]s Manual" "#VERSION#"
+.TH "fabtests" "7" "2024\-08\-03" "Libfabric Programmer\[cq]s Manual" "#VERSION#"
 .hy
 .SH NAME
 .PP
@@ -375,8 +375,7 @@ FI_WAIT_NONE, FI_WAIT_UNSPEC, FI_WAIT_FD, FI_WAIT_MUTEX_COND
 FI_WAIT_NONE, FI_WAIT_UNSPEC, FI_WAIT_FD, FI_WAIT_MUTEX_COND
 .TP
 \f[I]threading\f[R]
-FI_THREAD_UNSPEC, FI_THREAD_SAFE, FI_THREAD_FID, FI_THREAD_DOMAIN,
-FI_THREAD_COMPLETION, FI_THREAD_ENDPOINT
+FI_THREAD_UNSPEC, FI_THREAD_SAFE, FI_THREAD_DOMAIN, FI_THREAD_COMPLETION
 .TP
 \f[I]progress\f[R]
 FI_PROGRESS_MANUAL, FI_PROGRESS_AUTO, FI_PROGRESS_UNSPEC

man/man1/fi_info.1

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 2.9.2.1
 .\"
-.TH "fi_info" "1" "2024\-04\-01" "Libfabric Programmer\[cq]s Manual" "#VERSION#"
+.TH "fi_info" "1" "2024\-08\-03" "Libfabric Programmer\[cq]s Manual" "#VERSION#"
 .hy
 .SH NAME
 .PP
@@ -148,7 +148,6 @@ fi_info:
         mode: [  ]
         op_flags: [  ]
         msg_order: [ FI_ORDER_RAR, FI_ORDER_RAW, FI_ORDER_RAS, FI_ORDER_WAW, FI_ORDER_WAS, FI_ORDER_SAW, FI_ORDER_SAS, FI_ORDER_RMA_RAR, FI_ORDER_RMA_RAW, FI_ORDER_RMA_WAW, FI_ORDER_ATOMIC_RAR, FI_ORDER_ATOMIC_RAW, FI_ORDER_ATOMIC_WAR, FI_ORDER_ATOMIC_WAW ]
-        comp_order: [ FI_ORDER_NONE ]
         inject_size: 3840
         size: 1024
         iov_limit: 4
@@ -159,8 +158,6 @@ fi_info:
         mode: [  ]
         op_flags: [  ]
         msg_order: [ FI_ORDER_RAR, FI_ORDER_RAW, FI_ORDER_RAS, FI_ORDER_WAW, FI_ORDER_WAS, FI_ORDER_SAW, FI_ORDER_SAS, FI_ORDER_RMA_RAR, FI_ORDER_RMA_RAW, FI_ORDER_RMA_WAW, FI_ORDER_ATOMIC_RAR, FI_ORDER_ATOMIC_RAW, FI_ORDER_ATOMIC_WAR, FI_ORDER_ATOMIC_WAW ]
-        comp_order: [ FI_ORDER_NONE ]
-        total_buffered_recv: 0
         size: 1024
         iov_limit: 4
     fi_ep_attr:
@@ -180,8 +177,7 @@ fi_info:
         domain: 0x0
         name: mlx5_0-dgram
         threading: FI_THREAD_SAFE
-        control_progress: FI_PROGRESS_MANUAL
-        data_progress: FI_PROGRESS_MANUAL
+        progress: FI_PROGRESS_MANUAL
         resource_mgmt: FI_RM_ENABLED
         av_type: FI_AV_UNSPEC
         mr_mode: [  ]

man/man3/fi_av.3

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 2.9.2.1
 .\"
-.TH "fi_av" "3" "2023\-10\-31" "Libfabric Programmer\[cq]s Manual" "#VERSION#"
+.TH "fi_av" "3" "2024\-08\-03" "Libfabric Programmer\[cq]s Manual" "#VERSION#"
 .hy
 .SH NAME
 .PP
@@ -11,6 +11,7 @@ Open or close an address vector
 .TP
 fi_av_bind
 Associate an address vector with an event queue.
+This function is deprecated and should not be used.
 .TP
 fi_av_insert / fi_av_insertsvc / fi_av_remove
 Insert/remove an address into/from the address vector.
@@ -138,17 +139,17 @@ simpler, more efficient value that can be used by the libfabric API in a
 fabric agnostic way.
 The mapped address is of type fi_addr_t and is returned through an AV
 insertion call.
-The fi_addr_t is designed such that it may be a simple index into an
-array, a pointer to a structure, or a compact network address that may
-be placed directly into protocol headers.
 .PP
 The process of mapping an address is fabric and provider specific, but
 may involve lengthy address resolution and fabric management protocols.
-AV operations are synchronous by default, but may be set to operate
-asynchronously by specifying the FI_EVENT flag to \f[C]fi_av_open\f[R].
+AV operations are synchronous by default (the asynchrouous option has
+been deprecated, see below).
+See the NOTES section for AV restrictions on duplicate addresses.
+.PP
+\f[B]Deprecated\f[R]: AV operations may be set to operate asynchronously
+by specifying the FI_EVENT flag to \f[C]fi_av_open\f[R].
 When requesting asynchronous operation, the application must first bind
 an event queue to the AV before inserting addresses.
-See the NOTES section for AV restrictions on duplicate addresses.
 .SS fi_av_open
 .PP
 fi_av_open allocates or opens an address vector.
@@ -176,7 +177,7 @@ The type specifies how an application views data stored in the AV,
 including how it may be accessed.
 Valid values are:
 .TP
-- \f[I]FI_AV_MAP\f[R]
+- \f[I]FI_AV_MAP\f[R] (deprecated)
 Addresses which are inserted into an AV are mapped to a native fabric
 address for use by the application.
 The use of FI_AV_MAP requires that an application store the returned
@@ -191,6 +192,8 @@ store the returned addresses.
 Addresses are stored in the AV using a provider specific mechanism,
 including, but not limited to a tree, hash table, or maintained on the
 heap.
+This option is deprecated, and providers are encouraged to align the
+behavior of FI_AV_MAP with FI_AV_TABLE.
 .TP
 - \f[I]FI_AV_TABLE\f[R]
 Addresses which are inserted into an AV of type FI_AV_TABLE are
@@ -204,6 +207,11 @@ The index of the first address inserted into an FI_AV_TABLE will be 0,
 and successive insertions will be given sequential indices.
 Sequential indices will be assigned across insertion calls on the same
 AV.
+Because the fi_addr_t values returned from an insertion call are
+deterministic, applications may not need to provide the fi_addr_t output
+parameters to insertion calls.
+The exception is when the fi_addr_t parameters are also used as input
+for supplying authentication keys or user defined IDs.
 .TP
 - \f[I]FI_AV_UNSPEC\f[R]
 Provider will choose its preferred AV type.
@@ -265,7 +273,7 @@ The map_addr field is ignored if name is NULL.
 \f[I]flags\f[R]
 The following flags may be used when opening an AV.
 .TP
-- \f[I]FI_EVENT\f[R]
+- \f[I]FI_EVENT\f[R] (deprecated)
 When the flag FI_EVENT is specified, all insert operations on this AV
 will occur asynchronously.
 There will be one EQ error entry generated for each failed address
@@ -334,7 +342,7 @@ When closing the address vector, there must be no opened endpoints
 associated with the AV.
 If resources are still associated with the AV when attempting to close,
 the call will return -FI_EBUSY.
-.SS fi_av_bind
+.SS fi_av_bind (deprecated)
 .PP
 Associates an event queue with the AV.
 If an AV has been opened with \f[C]FI_EVENT\f[R], then an event queue
@@ -354,9 +362,9 @@ opening the corresponding domain.
 When using the \f[C]FI_ADDR_STR\f[R] format, the \f[C]addr\f[R]
 parameter should reference an array of strings (char **).
 .PP
-For AV\[cq]s of type FI_AV_MAP, once inserted addresses have been
-mapped, the mapped values are written into the buffer referenced by
-fi_addr.
+\f[B]Deprecated\f[R]: For AV\[cq]s of type FI_AV_MAP, once inserted
+addresses have been mapped, the mapped values are written into the
+buffer referenced by fi_addr.
 The fi_addr buffer must remain valid until the AV insertion has
 completed and an event has been generated to an associated event queue.
 The value of the returned fi_addr should be considered opaque by the
@@ -387,11 +395,6 @@ without using FI_SYNC_ERR flag, individual insertion failures cannot be
 reported and the application must use other calls, such as
 \f[C]fi_av_lookup\f[R] to learn which specific addresses failed to
 insert.
-Since fi_av_remove is provider-specific, it is recommended that calls to
-fi_av_insert following a call to fi_av_remove always reference a valid
-buffer in the fi_addr parameter.
-Otherwise it may be difficult to determine what the next assigned index
-will be.
 .PP
 If the address vector is configured with authorization keys, the fi_addr
 parameter may be used as input to define the authorization keys
@@ -512,19 +515,14 @@ Supported flags are the same as for fi_av_insert.
 .SS fi_av_remove
 .PP
 fi_av_remove removes a set of addresses from an address vector.
-All resources associated with the indicated addresses are released.
-The removed address - either the mapped address (in the case of
-FI_AV_MAP) or index (FI_AV_TABLE) - is invalid until it is returned
-again by a new fi_av_insert.
-.PP
+The corresponding fi_addr_t values are invalidated and may not be used
+in data transfer calls.
 The behavior of operations in progress that reference the removed
 addresses is undefined.
 .PP
-The use of fi_av_remove is an optimization that applications may use to
-free memory allocated with addresses that will no longer be accessed.
-Inserted addresses are not required to be removed.
-fi_av_close will automatically cleanup any resources associated with
-addresses remaining in the AV when it is invoked.
+Note that removing an address may not disable receiving data from the
+peer endpoint.
+fi_av_close will automatically cleanup any associated resource.
 .PP
 If the address being removed came from \f[C]fi_av_insert_auth_key\f[R],
 the address will only be removed if all endpoints, which have been
@@ -554,9 +552,6 @@ address, which may be larger than the input value.
 .PP
 This function is used to convert an endpoint address, returned by
 fi_av_insert, into an address that specifies a target receive context.
-The specified fi_addr parameter must either be a value returned from
-fi_av_insert, in the case of FI_AV_MAP, or an index, in the case of
-FI_AV_TABLE.
 The value for rx_ctx_bits must match that specified in the AV attributes
 for the given address.
 .PP
@@ -672,12 +667,6 @@ have been inserted into a given AV in order to avoid duplicate entries.
 However, providers are required to support the removal, followed by the
 re-insertion of an address.
 Only duplicate insertions are restricted.
-.PP
-Providers may implement AV\[cq]s using a variety of mechanisms.
-Specifically, a provider may begin resolving inserted addresses as soon
-as they have been added to an AV, even if asynchronous operation has
-been specified.
-Similarly, a provider may lazily release resources from removed entries.
 .SH USER IDENTIFIERS FOR ADDRESSES
 .PP
 As described above, endpoint addresses authorization keys that are
@@ -729,9 +718,10 @@ that were successfully inserted.
 In the case of failure, the return value will be less than the number of
 addresses that was specified.
 .PP
-Insertion calls, excluding \f[C]fi_av_insert_auth_key\f[R], for an AV
-opened for asynchronous operation (with FI_EVENT flag specified) will
-return FI_SUCCESS if the operation was successfully initiated.
+\f[B]Deprecated\f[R]: Insertion calls, excluding
+\f[C]fi_av_insert_auth_key\f[R], for an AV opened for asynchronous
+operation (with FI_EVENT flag specified) will return FI_SUCCESS if the
+operation was successfully initiated.
 In the case of failure, a negative fabric errno will be returned.
 Providers are allowed to abort insertion operations in the case of an
 error.

man/man3/fi_cntr.3

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 2.9.2.1
 .\"
-.TH "fi_cntr" "3" "2024\-03\-07" "Libfabric Programmer\[cq]s Manual" "#VERSION#"
+.TH "fi_cntr" "3" "2024\-08\-03" "Libfabric Programmer\[cq]s Manual" "#VERSION#"
 .hy
 .SH NAME
 .PP
@@ -105,7 +105,7 @@ The properties and behavior of the counter are defined by
 struct fi_cntr_attr {
     enum fi_cntr_events  events;    /* type of events to count */
     enum fi_wait_obj     wait_obj;  /* requested wait object */
-    struct fid_wait     *wait_set;  /* optional wait set */
+    struct fid_wait     *wait_set;  /* optional wait set, deprecated */
     uint64_t             flags;     /* operation flags */
 };
 \f[R]
@@ -153,7 +153,7 @@ Users may use fi_control to retrieve the underlying wait object
 associated with a counter, in order to use it in other system calls.
 The following values may be used to specify the type of wait object
 associated with a counter: FI_WAIT_NONE, FI_WAIT_UNSPEC, FI_WAIT_SET,
-FI_WAIT_FD, FI_WAIT_MUTEX_COND, and FI_WAIT_YIELD.
+FI_WAIT_FD, FI_WAIT_MUTEX_COND (deprecated), and FI_WAIT_YIELD.
 The default is FI_WAIT_NONE.
 .TP
 - \f[I]FI_WAIT_NONE\f[R]
@@ -169,7 +169,7 @@ mechanisms.
 Applications that select FI_WAIT_UNSPEC are not guaranteed to retrieve
 the underlying wait object.
 .TP
-- \f[I]FI_WAIT_SET\f[R]
+- \f[I]FI_WAIT_SET\f[R] (deprecated)
 Indicates that the event counter should use a wait set object to wait
 for events.
 If specified, the wait_set field must reference an existing wait set
@@ -183,7 +183,7 @@ routines.
 However, a provider may signal an FD wait object by marking it as
 readable, writable, or with an error.
 .TP
-- \f[I]FI_WAIT_MUTEX_COND\f[R]
+- \f[I]FI_WAIT_MUTEX_COND\f[R] (deprecated)
 Specifies that the counter should use a pthread mutex and cond variable
 as a wait object.
 .TP
@@ -192,7 +192,7 @@ Indicates that the counter will wait without a wait object but instead
 yield on every wait.
 Allows usage of fi_cntr_wait through a spin.
 .TP
-\f[I]wait_set\f[R]
+\f[I]wait_set\f[R] (deprecated)
 If wait_obj is FI_WAIT_SET, this field references a wait object to which
 the event counter should attach.
 When an event is added to the event counter, the corresponding wait set

man/man3/fi_cq.3

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 2.9.2.1
 .\"
-.TH "fi_cq" "3" "2024\-03\-07" "Libfabric Programmer\[cq]s Manual" "#VERSION#"
+.TH "fi_cq" "3" "2024\-08\-03" "Libfabric Programmer\[cq]s Manual" "#VERSION#"
 .hy
 .SH NAME
 .PP
@@ -134,7 +134,7 @@ struct fi_cq_attr {
     enum fi_wait_obj     wait_obj;  /* requested wait object */
     int                  signaling_vector; /* interrupt affinity */
     enum fi_cq_wait_cond wait_cond; /* wait condition format */
-    struct fid_wait     *wait_set;  /* optional wait set */
+    struct fid_wait     *wait_set;  /* optional wait set, deprecated */
 };
 \f[R]
 .fi
@@ -238,7 +238,7 @@ Users may use fi_control to retrieve the underlying wait object
 associated with a CQ, in order to use it in other system calls.
 The following values may be used to specify the type of wait object
 associated with a CQ: FI_WAIT_NONE, FI_WAIT_UNSPEC, FI_WAIT_SET,
-FI_WAIT_FD, FI_WAIT_MUTEX_COND, and FI_WAIT_YIELD.
+FI_WAIT_FD, FI_WAIT_MUTEX_COND (deprecated), and FI_WAIT_YIELD.
 The default is FI_WAIT_NONE.
 .TP
 - \f[I]FI_WAIT_NONE\f[R]
@@ -256,7 +256,7 @@ mechanisms.
 Applications that select FI_WAIT_UNSPEC are not guaranteed to retrieve
 the underlying wait object.
 .TP
-- \f[I]FI_WAIT_SET\f[R]
+- \f[I]FI_WAIT_SET\f[R] (deprecated)
 Indicates that the completion queue should use a wait set object to wait
 for completions.
 If specified, the wait_set field must reference an existing wait set
@@ -270,7 +270,7 @@ routines.
 However, a provider may signal an FD wait object by marking it as
 readable, writable, or with an error.
 .TP
-- \f[I]FI_WAIT_MUTEX_COND\f[R]
+- \f[I]FI_WAIT_MUTEX_COND\f[R] (deprecated)
 Specifies that the CQ should use a pthread mutex and cond variable as a
 wait object.
 .TP
@@ -310,7 +310,7 @@ before at the CQ before the wait is satisfied.
 .PP
 This field is ignored if wait_obj is set to FI_WAIT_NONE.
 .TP
-\f[I]wait_set\f[R]
+\f[I]wait_set\f[R] (deprecated)
 If wait_obj is FI_WAIT_SET, this field references a wait object to which
 the completion queue should attach.
 When an event is inserted into the completion queue, the corresponding
@@ -687,24 +687,6 @@ received message.
 If other flag bits are zero, the provider is reporting that the
 multi-recv buffer has been released, and the completion entry is not
 associated with a received message.
-.TP
-\f[I]FI_MORE\f[R]
-See the `Buffered Receives' section in \f[C]fi_msg\f[R](3) for more
-details.
-This flag is associated with receive completions on endpoints that have
-FI_BUFFERED_RECV mode enabled.
-When set to one, it indicates that the buffer referenced by the
-completion is limited by the FI_OPT_BUFFERED_LIMIT threshold, and
-additional message data must be retrieved by the application using an
-FI_CLAIM operation.
-.TP
-\f[I]FI_CLAIM\f[R]
-See the `Buffered Receives' section in \f[C]fi_msg\f[R](3) for more
-details.
-This flag is set on completions associated with receive operations that
-claim buffered receive data.
-Note that this flag only applies to endpoints configured with the
-FI_BUFFERED_RECV mode bit.
 .SH COMPLETION EVENT SEMANTICS
 .PP
 Libfabric defines several completion `levels', identified using