From 6f5e220fbf17ec0483e1ac125af9c60ebf2015d4 Mon Sep 17 00:00:00 2001 From: OFIWG Bot Date: Sat, 3 Aug 2024 04:03:21 +0000 Subject: [PATCH] Updated nroff-generated man pages Signed-off-by: OFIWG Bot --- fabtests/man/man7/fabtests.7 | 5 +- man/man1/fi_info.1 | 8 +- man/man3/fi_av.3 | 70 ++++++++--------- man/man3/fi_cntr.3 | 12 +-- man/man3/fi_cq.3 | 30 ++------ man/man3/fi_domain.3 | 81 +++++++++----------- man/man3/fi_endpoint.3 | 142 ++++++++++------------------------- man/man3/fi_eq.3 | 12 +-- man/man3/fi_getinfo.3 | 26 +++---- man/man3/fi_mr.3 | 7 +- man/man3/fi_msg.3 | 111 +-------------------------- man/man3/fi_poll.3 | 37 ++++----- man/man3/fi_tagged.3 | 58 +------------- man/man7/fi_setup.7 | 7 +- man/man7/fi_verbs.7 | 10 +-- 15 files changed, 171 insertions(+), 445 deletions(-) diff --git a/fabtests/man/man7/fabtests.7 b/fabtests/man/man7/fabtests.7 index 59bd17df5e6..e71d9c1f1ee 100644 --- a/fabtests/man/man7/fabtests.7 +++ b/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 diff --git a/man/man1/fi_info.1 b/man/man1/fi_info.1 index 7ca43b6566b..6f1dbc213e8 100644 --- a/man/man1/fi_info.1 +++ b/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: [ ] diff --git a/man/man3/fi_av.3 b/man/man3/fi_av.3 index aeae383abec..5b880bbaedc 100644 --- a/man/man3/fi_av.3 +++ b/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. diff --git a/man/man3/fi_cntr.3 b/man/man3/fi_cntr.3 index 4e88579f150..b01c900efea 100644 --- a/man/man3/fi_cntr.3 +++ b/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 diff --git a/man/man3/fi_cq.3 b/man/man3/fi_cq.3 index a1c36a632d4..da07f4fcb2f 100644 --- a/man/man3/fi_cq.3 +++ b/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 diff --git a/man/man3/fi_domain.3 b/man/man3/fi_domain.3 index 5781d51d3fb..ed719df3905 100644 --- a/man/man3/fi_domain.3 +++ b/man/man3/fi_domain.3 @@ -1,7 +1,7 @@ .\"t .\" Automatically generated by Pandoc 2.9.2.1 .\" -.TH "fi_domain" "3" "2024\-03\-07" "Libfabric Programmer\[cq]s Manual" "#VERSION#" +.TH "fi_domain" "3" "2024\-08\-03" "Libfabric Programmer\[cq]s Manual" "#VERSION#" .hy .SH NAME .PP @@ -39,6 +39,8 @@ Fabric domain .TP \f[I]info\f[R] Fabric information, including domain capabilities and attributes. +The struct fi_info must have been obtained using either fi_getinfo() or +fi_dupinfo(). .TP \f[I]domain\f[R] An opened access domain. @@ -164,9 +166,10 @@ This includes CM events. Endpoints may direct their control events to alternate EQs by binding directly with the EQ. .PP -Binding an event queue to a domain with the FI_REG_MR flag indicates -that the provider should perform all memory registration operations -asynchronously, with the completion reported through the event queue. +\f[B]Deprecated\f[R]: Binding an event queue to a domain with the +FI_REG_MR flag indicates that the provider should perform all memory +registration operations asynchronously, with the completion reported +through the event queue. If an event queue is not bound to the domain with the FI_REG_MR flag, then memory registration requests complete synchronously. .PP @@ -190,8 +193,7 @@ struct fi_domain_attr { struct fid_domain *domain; char *name; enum fi_threading threading; - enum fi_progress control_progress; - enum fi_progress data_progress; + enum fi_progress progress; enum fi_resource_mgmt resource_mgmt; enum fi_av_type av_type; int mr_mode; @@ -250,52 +252,38 @@ eliminate lower-level locks. The completion threading model is best suited for multi-threaded applications using scalable endpoints which desire lockless operation. Applications must serialize access to all objects that are associated by -a common completion mechanism (for example, endpoints bound to the same -CQ or counter). -It is recommended that providers which support scalable endpoints also +a common completion mechanism (for example, transmit and receive +contexts bound to the same CQ or counter). +It is recommended that providers which support scalable endpoints support this threading model. .PP -Applications wanting to leverage FI_THREAD_COMPLETION should allocate -transmit contexts, receive contexts, and completion queues and counters -to individual threads. +Applications wanting to leverage FI_THREAD_COMPLETION should dedicate +transmit contexts, receive contexts, completion queues, and counters to +individual threads. .TP \f[I]FI_THREAD_DOMAIN\f[R] -A domain serialization model requires applications to serialize access -to all objects belonging to a domain. -.TP -\f[I]FI_THREAD_ENDPOINT\f[R] +The domain threading model is best suited for single-threaded +applications and multi-threaded applications using standard endpoints +which desire lockless operation. +Applications must serialize access to all objects under the same domain. +This includes endpoints, transmit and receive contexts, completion +queues and counters, and registered memory regions. +.TP +\f[I]FI_THREAD_ENDPOINT\f[R] (deprecated) The endpoint threading model is similar to FI_THREAD_FID, but with the added restriction that serialization is required when accessing the same endpoint, even if multiple transmit and receive contexts are used. -Conceptually, FI_THREAD_ENDPOINT maps well to providers that implement -fabric services in hardware but use a single command queue to access -different data flows. .TP -\f[I]FI_THREAD_FID\f[R] +\f[I]FI_THREAD_FID\f[R] (deprecated) A fabric descriptor (FID) serialization model requires applications to serialize access to individual fabric resources associated with data transfer operations and completions. -Multiple threads must be serialized when accessing the same endpoint, -transmit context, receive context, completion queue, counter, wait set, -or poll set. -Serialization is required only by threads accessing the same object. -.PP -For example, one thread may be initiating a data transfer on an -endpoint, while another thread reads from a completion queue associated -with the endpoint. -.PP -Serialization to endpoint access is only required when accessing the +For endpoint access, serialization is only required when accessing the same endpoint data flow. Multiple threads may initiate transfers on different transmit contexts -of the same endpoint without serializing, and no serialization is +or the same endpoint without serializing, and no serialization is required between the submission of data transmit requests and data receive operations. -.PP -In general, FI_THREAD_FID allows the provider to be implemented without -needing internal locking when handling data transfers. -Conceptually, FI_THREAD_FID maps well to providers that implement fabric -services in hardware and provide separate command queues to different -data flows. .TP \f[I]FI_THREAD_SAFE\f[R] A thread safe serialization model allows a multi-threaded application to @@ -308,7 +296,7 @@ This value indicates that no threading model has been defined. It may be used on input hints to the fi_getinfo call. When specified, providers will return a threading model that allows for the greatest level of parallelism. -.SS Progress Models (control_progress / data_progress) +.SS Progress Models (progress) .PP Progress is the ability of the underlying implementation to complete processing of an asynchronous request. @@ -332,6 +320,12 @@ progress on data transfer operations. This includes message queue, RMA, tagged messaging, and atomic operations, along with their completion processing. .PP +The progress field defines the behavior of both control and data +operations. +For applications that require compilation portability between the +version 1 and version 2 libfabric series, the progress field may be +referenced as data_progress. +.PP Progress frequently requires action being taken at both the transmitting and receiving sides of an operation. This is often a requirement for reliable transfers, as a result of retry @@ -389,9 +383,8 @@ assistance to process received operations. This progress model indicates that the user will synchronize progressing the data and control operations themselves (i.e.\ this allows the control interface to NOT be thread safe). -It is only valid for control progress (not data progress). -Setting control=FI_PROGRESS_CONTROL_UNIFIED, data=FI_PROGRESS_MANUAL, -and threading=FI_THREAD_DOMAIN/FI_THREAD_COMPLETION allows Libfabric to +It implies manual progress, and when combined with +threading=FI_THREAD_DOMAIN/FI_THREAD_COMPLETION allows Libfabric to remove all locking in the critical data progress path. .TP \f[I]FI_PROGRESS_UNSPEC\f[R] @@ -718,7 +711,7 @@ than 64-bits. Indicates that the memory regions associated with completion counters must be explicitly enabled after being bound to any counter. .TP -\f[I]FI_MR_UNSPEC\f[R] +\f[I]FI_MR_UNSPEC\f[R] (deprecated) Defined for compatibility \[en] library versions 1.4 and earlier. Setting mr_mode to 0 indicates that FI_MR_BASIC or FI_MR_SCALABLE are requested and supported. @@ -727,14 +720,14 @@ requested and supported. Registered memory regions are referenced by peers using the virtual address of the registered memory region, rather than a 0-based offset. .TP -\f[I]FI_MR_BASIC\f[R] +\f[I]FI_MR_BASIC\f[R] (deprecated) Defined for compatibility \[en] library versions 1.4 and earlier. Only basic memory registration operations are requested or supported. This mode is equivalent to the FI_MR_VIRT_ADDR, FI_MR_ALLOCATED, and FI_MR_PROV_KEY flags being set in later library versions. This flag may not be used in conjunction with other mr_mode bits. .TP -\f[I]FI_MR_SCALABLE\f[R] +\f[I]FI_MR_SCALABLE\f[R] (deprecated) Defined for compatibility \[en] library versions 1.4 and earlier. Only scalable memory registration operations are requested or supported. Scalable registration uses offset based addressing, with application diff --git a/man/man3/fi_endpoint.3 b/man/man3/fi_endpoint.3 index b481b9c8392..f89f7844352 100644 --- a/man/man3/fi_endpoint.3 +++ b/man/man3/fi_endpoint.3 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 2.9.2.1 .\" -.TH "fi_endpoint" "3" "2024\-06\-19" "Libfabric Programmer\[cq]s Manual" "#VERSION#" +.TH "fi_endpoint" "3" "2024\-08\-03" "Libfabric Programmer\[cq]s Manual" "#VERSION#" .hy .SH NAME .PP @@ -122,8 +122,9 @@ address vector to bind to the endpoint. In other cases, it\[cq]s a fabric identifier of an associated resource. .TP \f[I]info\f[R] -Details about the fabric interface endpoint to be opened, obtained from -fi_getinfo. +Details about the fabric interface endpoint to be opened. +The struct fi_info must have been obtained using either fi_getinfo() or +fi_dupinfo(). .TP \f[I]ep\f[R] A fabric endpoint. @@ -523,40 +524,6 @@ The following option levels and option names and parameters are defined. \f[I]FI_OPT_ENDPOINT\f[R] \[bu] .RS 2 .TP -\f[I]FI_OPT_BUFFERED_LIMIT - size_t\f[R] -Defines the maximum size of a buffered message that will be reported to -users as part of a receive completion when the FI_BUFFERED_RECV mode is -enabled on an endpoint. -.PP -fi_getopt() will return the currently configured threshold, or the -provider\[cq]s default threshold if one has not be set by the -application. -fi_setopt() allows an application to configure the threshold. -If the provider cannot support the requested threshold, it will fail the -fi_setopt() call with FI_EMSGSIZE. -Calling fi_setopt() with the threshold set to SIZE_MAX will set the -threshold to the maximum supported by the provider. -fi_getopt() can then be used to retrieve the set size. -.PP -In most cases, the sending and receiving endpoints must be configured to -use the same threshold value, and the threshold must be set prior to -enabling the endpoint. -.RE -\[bu] .RS 2 -.TP -\f[I]FI_OPT_BUFFERED_MIN - size_t\f[R] -Defines the minimum size of a buffered message that will be reported. -Applications would set this to a size that\[cq]s big enough to decide -whether to discard or claim a buffered receive or when to claim a -buffered receive on getting a buffered receive completion. -The value is typically used by a provider when sending a rendezvous -protocol request where it would send at least FI_OPT_BUFFERED_MIN bytes -of application data along with it. -A smaller sized rendezvous protocol message usually results in better -latency for the overall transfer of a large message. -.RE -\[bu] .RS 2 -.TP \f[I]FI_OPT_CM_DATA_SIZE - size_t\f[R] Defines the size of available space in CM messages for user-defined data. @@ -1169,6 +1136,9 @@ Each set bit indicates that ordering is maintained between data transfers of the specified type. Message order is defined for [read | write | send] operations submitted by an application after [read | write | send] operations. +Value 0 indicates that no ordering is specified. +Value 0 may be used as input in order to obtain the default message +order supported by the provider. .PP Message ordering only applies to the end to end transmission of transport headers. @@ -1178,6 +1148,10 @@ Message ordering requires matching ordering semantics on the receiving side of a data transfer operation in order to guarantee that ordering is met. .TP +\f[I]FI_ORDER_NONE\f[R] (deprecated) +This is an alias for value 0. +It is deprecated and should not be used. +.TP \f[I]FI_ORDER_ATOMIC_RAR\f[R] Atomic read after read. If set, atomic fetch operations are transmitted in the order submitted @@ -1204,12 +1178,6 @@ relative to other atomic update operations. If not atomic updates may be transmitted out of order from their submission. .TP -\f[I]FI_ORDER_NONE\f[R] -No ordering is specified. -This value may be used as input in order to obtain the default message -order supported by the provider. -FI_ORDER_NONE is an alias for the value 0. -.TP \f[I]FI_ORDER_RAR\f[R] Read after read. If set, RMA and atomic read operations are transmitted in the order @@ -1298,38 +1266,20 @@ If not set, RMA and atomic writes may be transmitted out of order from their submission. .SS comp_order - Completion Ordering .PP +This field is provided for version 1 compatibility and should be set to +0. +.PP +\f[B]Deprecated\f[R] +.PP Completion ordering refers to the order in which completed requests are written into the completion queue. -Completion ordering is similar to message order. -Relaxed completion order may enable faster reporting of completed -transfers, allow acknowledgments to be sent over different fabric paths, -and support more sophisticated retry mechanisms. -This can result in lower-latency completions, particularly when using -connectionless endpoints. -Strict completion ordering may require that providers queue completed -operations or limit available optimizations. -.PP -For transmit requests, completion ordering depends on the endpoint -communication type. -For unreliable communication, completion ordering applies to all data -transfer requests submitted to an endpoint. -For reliable communication, completion ordering only applies to requests -that target a single destination endpoint. -Completion ordering of requests that target different endpoints over a -reliable transport is not defined. -.PP -Applications should specify the completion ordering that they support or -require. -Providers should return the completion order that they actually provide, -with the constraint that the returned ordering is stricter than that -specified by the application. Supported completion order values are: .TP -\f[I]FI_ORDER_NONE\f[R] +\f[I]FI_ORDER_NONE\f[R] (deprecated) No ordering is defined for completed operations. Requests submitted to the transmit context may complete in any order. .TP -\f[I]FI_ORDER_STRICT\f[R] +\f[I]FI_ORDER_STRICT\f[R] (deprecated) Requests complete in the order in which they are submitted to the transmit context. .SS inject_size @@ -1444,7 +1394,6 @@ struct fi_rx_attr { uint64_t op_flags; uint64_t msg_order; uint64_t comp_order; - size_t total_buffered_recv; size_t size; size_t iov_limit; }; @@ -1499,52 +1448,40 @@ Typically, this means that messages will be handled in order based on a message level sequence number. .PP The following ordering flags, as defined for transmit ordering, also -apply to the processing of received operations: FI_ORDER_NONE, -FI_ORDER_RAR, FI_ORDER_RAW, FI_ORDER_RAS, FI_ORDER_WAR, FI_ORDER_WAW, -FI_ORDER_WAS, FI_ORDER_SAR, FI_ORDER_SAW, FI_ORDER_SAS, -FI_ORDER_RMA_RAR, FI_ORDER_RMA_RAW, FI_ORDER_RMA_WAR, FI_ORDER_RMA_WAW, +apply to the processing of received operations: FI_ORDER_RAR, +FI_ORDER_RAW, FI_ORDER_RAS, FI_ORDER_WAR, FI_ORDER_WAW, FI_ORDER_WAS, +FI_ORDER_SAR, FI_ORDER_SAW, FI_ORDER_SAS, FI_ORDER_RMA_RAR, +FI_ORDER_RMA_RAW, FI_ORDER_RMA_WAR, FI_ORDER_RMA_WAW, FI_ORDER_ATOMIC_RAR, FI_ORDER_ATOMIC_RAW, FI_ORDER_ATOMIC_WAR, and FI_ORDER_ATOMIC_WAW. .SS comp_order - Completion Ordering .PP -For a description of completion ordering, see the comp_order field in -the \f[I]Transmit Context Attribute\f[R] section. +This field is provided for version 1 compatibility and should be set to +0. +.PP +\f[B]Deprecated\f[R] +.PP +Completion ordering refers to the order in which completed requests are +written into the completion queue. +Supported completion order values are: .TP -\f[I]FI_ORDER_DATA\f[R] +\f[I]FI_ORDER_DATA\f[R] (deprecated) When set, this bit indicates that received data is written into memory in order. Data ordering applies to memory accessed as part of a single operation and between operations if message ordering is guaranteed. .TP -\f[I]FI_ORDER_NONE\f[R] +\f[I]FI_ORDER_NONE\f[R] (deprecated) No ordering is defined for completed operations. -Receive operations may complete in any order, regardless of their -submission order. +Requests submitted to the transmit context may complete in any order. .TP -\f[I]FI_ORDER_STRICT\f[R] -Receive operations complete in the order in which they are processed by -the receive context, based on the receive side msg_order attribute. +\f[I]FI_ORDER_STRICT\f[R] (deprecated) +Requests complete in the order in which they are submitted to the +transmit context. .SS total_buffered_recv .PP -This field is supported for backwards compatibility purposes. -It is a hint to the provider of the total available space that may be -needed to buffer messages that are received for which there is no -matching receive operation. -The provider may adjust or ignore this value. -The allocation of internal network buffering among received message is -provider specific. -For instance, a provider may limit the size of messages which can be -buffered or the amount of buffering allocated to a single message. -.PP -If receive side buffering is disabled (total_buffered_recv = 0) and a -message is received by an endpoint, then the behavior is dependent on -whether resource management has been enabled (FI_RM_ENABLED has be set -or not). -See the Resource Management section of fi_domain.3 for further -clarification. -It is recommended that applications enable resource management if they -anticipate receiving unexpected messages, rather than modifying this -value. +This field is provided for version 1 compatibility and should be set to +0. .SS size .PP The size of the receive context. @@ -1851,8 +1788,7 @@ minimal set of requirements (such that the application maintains correctness). However, it can also return provider info structures that exceed application requirements. -As an example, consider an application requesting msg_order as -FI_ORDER_NONE. +As an example, consider an application requesting no msg_order. The resulting output from fi_getinfo may have all the ordering bits set. The application can reset the ordering bits it does not require before creating the endpoint. diff --git a/man/man3/fi_eq.3 b/man/man3/fi_eq.3 index 707474fd843..249c086cc3b 100644 --- a/man/man3/fi_eq.3 +++ b/man/man3/fi_eq.3 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 2.9.2.1 .\" -.TH "fi_eq" "3" "2022\-12\-09" "Libfabric Programmer\[cq]s Manual" "#VERSION#" +.TH "fi_eq" "3" "2024\-08\-03" "Libfabric Programmer\[cq]s Manual" "#VERSION#" .hy .SH NAME .PP @@ -118,7 +118,7 @@ struct fi_eq_attr { uint64_t flags; /* operation flags */ enum fi_wait_obj wait_obj; /* requested wait object */ int signaling_vector; /* interrupt affinity */ - struct fid_wait *wait_set; /* optional wait set */ + struct fid_wait *wait_set; /* optional wait set, deprecated */ }; \f[R] .fi @@ -165,7 +165,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 queue should use a wait set object to wait for events. If specified, the wait_set field must reference an existing wait set @@ -179,7 +179,7 @@ routines. However, a provider may signal an FD wait object by marking it as readable 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 EQ should use a pthread mutex and cond variable as a wait object. .TP @@ -194,7 +194,7 @@ If the FI_AFFINITY flag is set, this indicates the logical cpu number This field should be treated as a hint to the provider and may be ignored if the provider does not support interrupt affinity. .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 queue should attach. When an event is inserted into the event queue, the corresponding wait @@ -225,7 +225,7 @@ the EQ attributes. The fi_control arg parameter should be an address where a pointer to the returned wait object will be written. This should be an \[cq]int *\[cq] for FI_WAIT_FD, or `struct -fi_mutex_cond' for FI_WAIT_MUTEX_COND. +fi_mutex_cond' for FI_WAIT_MUTEX_COND (deprecated). .IP .nf \f[C] diff --git a/man/man3/fi_getinfo.3 b/man/man3/fi_getinfo.3 index d79af2fc56d..5b35475bb68 100644 --- a/man/man3/fi_getinfo.3 +++ b/man/man3/fi_getinfo.3 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 2.9.2.1 .\" -.TH "fi_getinfo" "3" "2024\-05\-07" "Libfabric Programmer\[cq]s Manual" "#VERSION#" +.TH "fi_getinfo" "3" "2024\-08\-03" "Libfabric Programmer\[cq]s Manual" "#VERSION#" .hy .SH NAME .PP @@ -40,6 +40,8 @@ Operation flags for the fi_getinfo call. \f[I]hints\f[R] Reference to an fi_info structure that specifies criteria for selecting the returned fabric information. +The fi_info hints structure must be allocated using either +fi_allocinfo() or fi_dupinfo(). .TP \f[I]info\f[R] A pointer to a linked list of fi_info structures containing response @@ -547,18 +549,6 @@ When set, an application must not modify an IO vector of length > 1, including any related memory descriptor array, until the associated operation has completed. .TP -\f[I]FI_BUFFERED_RECV\f[R] -The buffered receive mode bit indicates that the provider owns the data -buffer(s) that are accessed by the networking layer for received -messages. -Typically, this implies that data must be copied from the provider -buffer into the application buffer. -Applications that can handle message processing from network allocated -data buffers can set this mode bit to avoid copies. -For full details on application requirements to support this mode, see -the `Buffered Receives' section in \f[C]fi_msg\f[R](3). -This mode bit applies to FI_MSG and FI_TAGGED receive operations. -.TP \f[I]FI_CONTEXT\f[R] Specifies that the provider requires that applications use struct fi_context as their per operation context parameter for operations that @@ -591,7 +581,7 @@ structures (e.g.\ struct fi_context[2]) instead. The requirements for using struct fi_context2 are identical as defined for FI_CONTEXT above. .TP -\f[I]FI_LOCAL_MR\f[R] +\f[I]FI_LOCAL_MR\f[R] (deprecated) The provider is optimized around having applications register memory for locally accessed data buffers. Data buffers used in send and receive operations and as the source @@ -775,6 +765,14 @@ Indicates that there was insufficient memory to complete the operation. Indicates that requested version is newer than the library being used. .SH NOTES .PP +Various libfabric calls, including fi_getinfo, take a struct fi_info as +input. +Applications must use libfabric allocated fi_info structures. +A zeroed struct fi_info can be allocated using fi_allocinfo, which may +then be initialized by the user. +A struct fi_info may be copied for modification using the fi_dupinfo() +call. +.PP If hints are provided, the operation will be controlled by the values that are supplied in the various fields (see section on \f[I]fi_info\f[R]). diff --git a/man/man3/fi_mr.3 b/man/man3/fi_mr.3 index d8068d98537..f9ffbc1e841 100644 --- a/man/man3/fi_mr.3 +++ b/man/man3/fi_mr.3 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 2.9.2.1 .\" -.TH "fi_mr" "3" "2024\-06\-14" "Libfabric Programmer\[cq]s Manual" "#VERSION#" +.TH "fi_mr" "3" "2024\-08\-03" "Libfabric Programmer\[cq]s Manual" "#VERSION#" .hy .SH NAME .PP @@ -376,7 +376,7 @@ Applications may optionally pass in a valid desc parameter. If the desc parameter is NULL, any required local memory registration will be handled by the provider. .TP -\f[I]Basic Memory Registration\f[R] +\f[I]Basic Memory Registration\f[R] (deprecated) Basic memory registration was deprecated in libfabric version 1.5, but is supported for backwards compatibility. Basic memory registration is indicated by setting mr_mode equal to @@ -401,7 +401,8 @@ The main difference between registration functions are the number and type of parameters that they accept as input. Otherwise, they perform the same general function. .PP -By default, memory registration completes synchronously. +\f[B]Deprecated\f[R] : By default, memory registration completes +synchronously. I.e. the registration call will not return until the registration has completed. diff --git a/man/man3/fi_msg.3 b/man/man3/fi_msg.3 index a8f13b7b7f6..0fe3a855391 100644 --- a/man/man3/fi_msg.3 +++ b/man/man3/fi_msg.3 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 2.9.2.1 .\" -.TH "fi_msg" "3" "2024\-03\-07" "Libfabric Programmer\[cq]s Manual" "#VERSION#" +.TH "fi_msg" "3" "2024\-08\-03" "Libfabric Programmer\[cq]s Manual" "#VERSION#" .hy .SH NAME .PP @@ -220,13 +220,6 @@ the request. See fi_getinfo for additional details on FI_REMOTE_CQ_DATA. This flag is implicitly set for fi_senddata and fi_injectdata. .TP -\f[I]FI_CLAIM\f[R] -Applies to posted receive operations for endpoints configured for -FI_BUFFERED_RECV. -This flag is used to retrieve a message that was buffered by the -provider. -See the Buffered Receives section for details. -.TP \f[I]FI_COMPLETION\f[R] Indicates that a completion entry should be generated for the specified operation. @@ -234,12 +227,6 @@ The endpoint must be bound to a completion queue with FI_SELECTIVE_COMPLETION that corresponds to the specified operation, or this flag is ignored. .TP -\f[I]FI_DISCARD\f[R] -Applies to posted receive operations for endpoints configured for -FI_BUFFERED_RECV. -This flag is used to free a message that was buffered by the provider. -See the Buffered Receives section for details. -.TP \f[I]FI_MORE\f[R] Indicates that the user has additional requests that will immediately be posted after the current call returns. @@ -319,102 +306,6 @@ Only valid with domains configured with FI_AV_AUTH_KEY and connectionless endpoints configured with FI_DIRECTED_RECV. When used with fi_recvmsg, this flag denotes that the src_addr is an authorization key fi_addr_t instead of an endpoint fi_addr_t. -.SH Buffered Receives -.PP -Buffered receives indicate that the networking layer allocates and -manages the data buffers used to receive network data transfers. -As a result, received messages must be copied from the network buffers -into application buffers for processing. -However, applications can avoid this copy if they are able to process -the message in place (directly from the networking buffers). -.PP -Handling buffered receives differs based on the size of the message -being sent. -In general, smaller messages are passed directly to the application for -processing. -However, for large messages, an application will only receive the start -of the message and must claim the rest. -The details for how small messages are reported and large messages may -be claimed are described below. -.PP -When a provider receives a message, it will write an entry to the -completion queue associated with the receiving endpoint. -For discussion purposes, the completion queue is assumed to be -configured for FI_CQ_FORMAT_DATA. -Since buffered receives are not associated with application posted -buffers, the CQ entry op_context will point to a struct fi_recv_context. -.IP -.nf -\f[C] -struct fi_recv_context { - struct fid_ep *ep; - void *context; -}; -\f[R] -.fi -.PP -The `ep' field will point to the receiving endpoint or Rx context, and -`context' will be NULL. -The CQ entry\[cq]s `buf' will point to a provider managed buffer where -the start of the received message is located, and `len' will be set to -the total size of the message. -.PP -The maximum sized message that a provider can buffer is limited by an -FI_OPT_BUFFERED_LIMIT. -This threshold can be obtained and may be adjusted by the application -using the fi_getopt and fi_setopt calls, respectively. -Any adjustments must be made prior to enabling the endpoint. -The CQ entry `buf' will point to a buffer of received data. -If the sent message is larger than the buffered amount, the CQ entry -`flags' will have the FI_MORE bit set. -When the FI_MORE bit is set, `buf' will reference at least -FI_OPT_BUFFERED_MIN bytes of data (see fi_endpoint.3 for more info). -.PP -After being notified that a buffered receive has arrived, applications -must either claim or discard the message. -Typically, small messages are processed and discarded, while large -messages are claimed. -However, an application is free to claim or discard any message -regardless of message size. -.PP -To claim a message, an application must post a receive operation with -the FI_CLAIM flag set. -The struct fi_recv_context returned as part of the notification must be -provided as the receive operation\[cq]s context. -The struct fi_recv_context contains a `context' field. -Applications may modify this field prior to claiming the message. -When the claim operation completes, a standard receive completion entry -will be generated on the completion queue. -The `context' of the associated CQ entry will be set to the `context' -value passed in through the fi_recv_context structure, and the CQ entry -flags will have the FI_CLAIM bit set. -.PP -Buffered receives that are not claimed must be discarded by the -application when it is done processing the CQ entry data. -To discard a message, an application must post a receive operation with -the FI_DISCARD flag set. -The struct fi_recv_context returned as part of the notification must be -provided as the receive operation\[cq]s context. -When the FI_DISCARD flag is set for a receive operation, the receive -input buffer(s) and length parameters are ignored. -.PP -IMPORTANT: Buffered receives must be claimed or discarded in a timely -manner. -Failure to do so may result in increased memory usage for network -buffering or communication stalls. -Once a buffered receive has been claimed or discarded, the original CQ -entry `buf' or struct fi_recv_context data may no longer be accessed by -the application. -.PP -The use of the FI_CLAIM and FI_DISCARD operation flags is also described -with respect to tagged message transfers in fi_tagged.3. -Buffered receives of tagged messages will include the message tag as -part of the CQ entry, if available. -.PP -The handling of buffered receives follows all message ordering -restrictions assigned to an endpoint. -For example, completions may indicate the order in which received -messages arrived at the receiver based on the endpoint attributes. .SH NOTES .PP If an endpoint has been configured with FI_MSG_PREFIX, the application diff --git a/man/man3/fi_poll.3 b/man/man3/fi_poll.3 index 9d528a91273..285965f3589 100644 --- a/man/man3/fi_poll.3 +++ b/man/man3/fi_poll.3 @@ -1,25 +1,25 @@ .\" Automatically generated by Pandoc 2.9.2.1 .\" -.TH "fi_poll" "3" "2022\-12\-09" "Libfabric Programmer\[cq]s Manual" "#VERSION#" +.TH "fi_poll" "3" "2024\-08\-03" "Libfabric Programmer\[cq]s Manual" "#VERSION#" .hy .SH NAME .PP -fi_poll - Polling and wait set operations +fi_poll - Polling and wait set operations (deprecated) .TP -fi_poll_open / fi_close +fi_poll_open / fi_close (deprecated) Open/close a polling set .TP -fi_poll_add / fi_poll_del +fi_poll_add / fi_poll_del (deprecated) Add/remove a completion queue or counter to/from a poll set. .TP -fi_poll +fi_poll (deprecated) Poll for progress and events across multiple completion queues and counters. .TP -fi_wait_open / fi_close +fi_wait_open / fi_close (deprecated) Open/close a wait set .TP -fi_wait +fi_wait (deprecated) Waits for one or more wait objects in a set to be signaled. .TP fi_trywait @@ -95,7 +95,7 @@ Command of control operation to perform on the wait set. \f[I]arg\f[R] Optional control argument. .SH DESCRIPTION -.SS fi_poll_open +.SS fi_poll_open (deprecated) .PP fi_poll_open creates a new polling set. A poll set enables an optimized method for progressing asynchronous @@ -115,18 +115,18 @@ struct fi_poll_attr { \f[I]flags\f[R] Flags that set the default operation of the poll set. The use of this field is reserved and must be set to 0 by the caller. -.SS fi_close +.SS fi_close (deprecated) .PP The fi_close call releases all resources associated with a poll set. The poll set must not be associated with any other resources prior to being closed, otherwise the call will return -FI_EBUSY. -.SS fi_poll_add +.SS fi_poll_add (deprecated) .PP Associates a completion queue or counter with a poll set. -.SS fi_poll_del +.SS fi_poll_del (deprecated) .PP Removes a completion queue or counter from a poll set. -.SS fi_poll +.SS fi_poll (deprecated) .PP Progresses all completion queues and counters associated with a poll set and checks for events. @@ -147,7 +147,7 @@ Applications should drive their progress based on the results of reading events from a completion queue or reading counter values. The fi_poll function will always return all completion queues and counters that do have new events. -.SS fi_wait_open +.SS fi_wait_open (deprecated) .PP fi_wait_open allocates a new wait set. A wait set enables an optimized method of waiting for events across @@ -174,7 +174,7 @@ Wait objects allow applications to block until the wait object is signaled, indicating that an event is available to be read. The following values may be used to specify the type of wait object associated with a wait set: FI_WAIT_UNSPEC, FI_WAIT_FD, -FI_WAIT_MUTEX_COND, and FI_WAIT_YIELD. +FI_WAIT_MUTEX_COND (deprecated), and FI_WAIT_YIELD. .TP - \f[I]FI_WAIT_UNSPEC\f[R] Specifies that the user will only wait on the wait set using fabric @@ -195,7 +195,7 @@ poll(2), and Linux epoll(7) routines (if available). Provider signal an FD wait object by marking it as readable 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 wait set should use a pthread mutex and cond variable as a wait object. .TP @@ -217,12 +217,12 @@ yield on every wait. \f[I]flags\f[R] Flags that set the default operation of the wait set. The use of this field is reserved and must be set to 0 by the caller. -.SS fi_close +.SS fi_close (deprecated) .PP The fi_close call releases all resources associated with a wait set. The wait set must not be bound to any other opened resources prior to being closed, otherwise the call will return -FI_EBUSY. -.SS fi_wait +.SS fi_wait (deprecated) .PP Waits on a wait set until one or more of its underlying wait objects is signaled. @@ -303,7 +303,8 @@ through the wait set attributes. The fi_control arg parameter should be an address where a pointer to the returned wait object will be written. This should be an \[cq]int *\[cq] for FI_WAIT_FD, `struct fi_mutex_cond' -for FI_WAIT_MUTEX_COND, or `struct fi_wait_pollfd' for FI_WAIT_POLLFD. +for FI_WAIT_MUTEX_COND (deprecated), or `struct fi_wait_pollfd' for +FI_WAIT_POLLFD. Support for FI_GETWAIT is provider specific. .TP \f[I]FI_GETWAITOBJ (enum fi_wait_obj *)\f[R] diff --git a/man/man3/fi_tagged.3 b/man/man3/fi_tagged.3 index 92a3297d8e3..62d48a21298 100644 --- a/man/man3/fi_tagged.3 +++ b/man/man3/fi_tagged.3 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 2.9.2.1 .\" -.TH "fi_tagged" "3" "2024\-06\-19" "Libfabric Programmer\[cq]s Manual" "#VERSION#" +.TH "fi_tagged" "3" "2024\-08\-03" "Libfabric Programmer\[cq]s Manual" "#VERSION#" .hy .SH NAME .PP @@ -310,7 +310,7 @@ The following flags may be used with fi_trecvmsg. \f[I]FI_PEEK\f[R] The peek flag may be used to see if a specified message has arrived. A peek request is often useful on endpoints that have provider allocated -buffering enabled (see fi_rx_attr total_buffered_recv). +buffering enabled. Unlike standard receive operations, a receive operation with the FI_PEEK flag set does not remain queued with the provider after the peek completes successfully. @@ -339,15 +339,9 @@ A receive operation with the FI_CLAIM flag set, but FI_PEEK not set is used to retrieve a previously claimed message. .PP In order to use the FI_CLAIM flag, an application must supply a struct -fi_context structure as the context for the receive operation, or a -struct fi_recv_context in the case of buffered receives. +fi_context structure as the context for the receive operation. The same fi_context structure used for an FI_PEEK + FI_CLAIM operation must be used by the paired FI_CLAIM request. -.PP -This flag also applies to endpoints configured for FI_BUFFERED_RECV. -When set, it is used to retrieve a tagged message that was buffered by -the provider. -See Buffered Tagged Receives section for details. .TP \f[I]FI_DISCARD\f[R] This flag may be used in conjunction with either FI_PEEK or FI_CLAIM. @@ -359,54 +353,8 @@ This flag may also be used in conjunction with FI_CLAIM in order to discard a message previously claimed using an FI_PEEK + FI_CLAIM request. .PP -This flag also applies to endpoints configured for FI_BUFFERED_RECV. -When set, it indicates that the provider should free a buffered -messages. -See Buffered Tagged Receives section for details. -.PP If this flag is set, the input buffer(s) and length parameters are ignored. -.SH Buffered Tagged Receives -.PP -See \f[C]fi_msg\f[R](3) for an introduction to buffered receives. -The handling of buffered receives differs between fi_msg operations and -fi_tagged. -Although the provider is responsible for allocating and managing network -buffers, the application is responsible for identifying the tags that -will be used to match incoming messages. -The provider handles matching incoming receives to the application -specified tags. -.PP -When FI_BUFFERED_RECV is enabled, the application posts the tags that -will be used for matching purposes. -Tags are posted using fi_trecv, fi_trecvv, and fi_trecvmsg; however, -parameters related to the input buffers are ignored (e.g.\ buf, len, -iov, desc). -When a provider receives a message for which there is a matching tag, it -will write an entry to the completion queue associated with the -receiving endpoint. -.PP -For discussion purposes, the completion queue is assumed to be -configured for FI_CQ_FORMAT_TAGGED. -The op_context field will point to a struct fi_recv_context. -.IP -.nf -\f[C] -struct fi_recv_context { - struct fid_ep *ep; - void *context; -}; -\f[R] -.fi -.PP -The `ep' field will be NULL. -The `context' field will match the application context specified when -posting the tag. -Other fields are set as defined in \f[C]fi_msg\f[R](3). -.PP -After being notified that a buffered receive has arrived, applications -must either claim or discard the message as described in -\f[C]fi_msg\f[R](3). .SH RETURN VALUE .PP The tagged send and receive calls return 0 on success. diff --git a/man/man7/fi_setup.7 b/man/man7/fi_setup.7 index 47fab7e874b..ebb88bddee3 100644 --- a/man/man7/fi_setup.7 +++ b/man/man7/fi_setup.7 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 2.9.2.1 .\" -.TH "fi_setup" "7" "2024\-03\-20" "Libfabric Programmer\[cq]s Manual" "#VERSION#" +.TH "fi_setup" "7" "2024\-08\-03" "Libfabric Programmer\[cq]s Manual" "#VERSION#" .hy .SH NAME .PP @@ -435,8 +435,7 @@ struct fi_domain_attr { struct fid_domain *domain; char *name; enum fi_threading threading; - enum fi_progress control_progress; - enum fi_progress data_progress; + enum fi_progress progress; enum fi_resource_mgmt resource_mgmt; enum fi_av_type av_type; enum fi_mr_mode mr_mode; @@ -893,7 +892,6 @@ struct fi_rx_attr { uint64_t mode; uint64_t op_flags; uint64_t msg_order; - uint64_t comp_order; ... }; @@ -902,7 +900,6 @@ struct fi_tx_attr { uint64_t mode; uint64_t op_flags; uint64_t msg_order; - uint64_t comp_order; size_t inject_size; ... }; diff --git a/man/man7/fi_verbs.7 b/man/man7/fi_verbs.7 index a9df41bb497..a4b8653ea0d 100644 --- a/man/man7/fi_verbs.7 +++ b/man/man7/fi_verbs.7 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 2.9.2.1 .\" -.TH "fi_verbs" "7" "2024\-06\-27" "Libfabric Programmer\[cq]s Manual" "#VERSION#" +.TH "fi_verbs" "7" "2024\-08\-03" "Libfabric Programmer\[cq]s Manual" "#VERSION#" .hy .SH NAME .PP @@ -50,7 +50,7 @@ FI_MSG Verbs provider requires applications to support the following modes: .SS FI_EP_MSG endpoint type .IP \[bu] 2 -FI_LOCAL_MR / FI_MR_LOCAL mr mode. +FI_MR_LOCAL mr mode. .IP \[bu] 2 FI_RX_CQ_DATA for applications that want to use RMA. Applications must take responsibility of posting receives for any @@ -85,12 +85,6 @@ Write after Send Send after Write .IP \[bu] 2 Send after Send -.PP -and the following completion ordering: -.IP \[bu] 2 -TX contexts: FI_ORDER_STRICT -.IP \[bu] 2 -RX contexts: FI_ORDER_DATA .SS Fork .PP Verbs provider does not provide fork safety by default.