Update nroff-generated man pages

man/man3/fi_fabric.3

@@ -1,13 +1,13 @@
 .\" Automatically generated by Pandoc 2.5
 .\"
-.TH "fi_fabric" "3" "2021\-03\-22" "Libfabric Programmer\[cq]s Manual" "#VERSION#"
+.TH "fi_fabric" "3" "2021\-06\-05" "Libfabric Programmer\[cq]s Manual" "#VERSION#"
 .hy
 .SH NAME
 .PP
-fi_fabric \- Fabric domain operations
+fi_fabric \- Fabric network operations
 .TP
 .B fi_fabric / fi_close
-Open / close a fabric domain
+Open / close a fabric network
 .TP
 .B fi_tostr / fi_tostr_r
 Convert fabric attributes, flags, and capabilities to printable string
@@ -34,7 +34,7 @@ char * fi_tostr(char *buf, size_t len, const void *data,
 Attributes of fabric to open.
 .TP
 .B \f[I]fabric\f[R]
-Fabric domain
+Fabric network
 .TP
 .B \f[I]context\f[R]
 User specified context associated with the opened object.
@@ -54,21 +54,26 @@ The format of data is determined by the datatype parameter.
 Indicates the data to convert to a printable string.
 .SH DESCRIPTION
 .PP
-A fabric domain represents a collection of hardware and software
+A fabric identifier is used to reference opened fabric resources and
+library related objects.
+.PP
+The fabric network represents a collection of hardware and software
 resources that access a single physical or virtual network.
 All network ports on a system that can communicate with each other
-through their attached networks belong to the same fabric domain.
-A fabric domain shares network addresses and can span multiple
+through their attached networks belong to the same fabric.
+A fabric network shares network addresses and can span multiple
 providers.
+An application must open a fabric network prior to allocating other
+network resources, such as communication endpoints.
 .SS fi_fabric
 .PP
-Opens a fabric provider.
+Opens a fabric network provider.
 The attributes of the fabric provider are specified through the open
 call, and may be obtained by calling fi_getinfo.
 .SS fi_close
 .PP
 The fi_close call is used to release all resources associated with a
-fabric domain or interface.
+fabric object.
 All items associated with the opened fabric must be released prior to
 calling fi_close.
 .SS fi_tostr / fi_tostr_r

man/man3/fi_mr.3

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 2.5
 .\"
-.TH "fi_mr" "3" "2021\-05\-25" "Libfabric Programmer\[cq]s Manual" "#VERSION#"
+.TH "fi_mr" "3" "2021\-06\-05" "Libfabric Programmer\[cq]s Manual" "#VERSION#"
 .hy
 .SH NAME
 .PP
@@ -848,6 +848,14 @@ an application and the underlying device physical pages.
 Valid monitor options are: 0 or 1.
 Note that the ROCR memory monitor requires a ROCR version with unified
 virtual addressing enabled.
+.PP
+More direct access to the internal registration cache is possible
+through the fi_open() call, using the \[lq]mr_cache\[rq] service name.
+Once opened, custom memory monitors may be installed.
+A memory monitor is a component of the cache responsible for detecting
+changes in virtual to physical address mappings.
+Some level of control over the cache is possible through the above
+mentioned environment variables.
 .SH SEE ALSO
 .PP
 \f[C]fi_getinfo\f[R](3), \f[C]fi_endpoint\f[R](3),

man/man3/fi_provider.3

@@ -1 +1,225 @@
-.so man3/fi_provider.3
+.\" Automatically generated by Pandoc 2.5
+.\"
+.TH "fi_provider" "3" "2021\-06\-05" "Libfabric Programmer\[cq]s Manual" "#VERSION#"
+.hy
+.SH NAME
+.PP
+fi_prov_ini \- External provider entry point
+.TP
+.B fi_param_define / fi_param_get
+Register and retrieve environment variables with the libfabric core
+.TP
+.B fi_log_enabled / fi_log
+Control and output debug logging information.
+.TP
+.B fi_open / fi_close
+Open a named library object
+.TP
+.B fi_export_fid / fi_import_fid
+Share a fabric object between different providers or resources
+.SH SYNOPSIS
+.IP
+.nf
+\f[C]
+#include <rdma/fabric.h>
+#include <rdma/prov/fi_prov.h>
+
+struct fi_provider* fi_prov_ini(void);
+
+int fi_param_define(const struct fi_provider *provider, const char *param_name,
+    enum fi_param_type type, const char *help_string_fmt, ...);
+
+int fi_param_get_str(struct fi_provider *provider, const char *param_name,
+    char **value);
+
+int fi_param_get_int(struct fi_provider *provider, const char *param_name,
+    int *value);
+
+int fi_param_get_bool(struct fi_provider *provider, const char *param_name,
+    int *value);
+
+int fi_param_get_size_t(struct fi_provider *provider, const char *param_name,
+    size_t *value);
+\f[R]
+.fi
+.IP
+.nf
+\f[C]
+#include <rdma/fabric.h>
+#include <rdma/prov/fi_prov.h>
+#include <rdma/prov/fi_log.h>
+
+int fi_log_enabled(const struct fi_provider *prov, enum fi_log_level level,
+    enum fi_log_subsys subsys);
+
+void fi_log(const struct fi_provider *prov, enum fi_log_level level,
+    enum fi_log_subsys subsys, const char *func, int line,
+    const char *fmt, ...);
+\f[R]
+.fi
+.IP
+.nf
+\f[C]
+#include <rdma/fabric.h>
+
+int fi_open(uint32_t version, const char *name, void *attr,
+    size_t attr_len, uint64_t flags, struct fid **fid, void *context);
+
+int fi_close(struct fid *fid);
+\f[R]
+.fi
+.IP
+.nf
+\f[C]
+#include <rdma/fabric.h>
+#include <rdma/fi_ext.h>
+
+int fi_export_fid(struct fid *fid, uint64_t flags,
+    struct fid **expfid, void *context);
+
+int fi_import_fid(struct fid *fid, struct fid *expfid, uint64_t flags);
+\f[R]
+.fi
+.SH ARGUMENTS
+.TP
+.B \f[I]provider\f[R]
+Reference to the provider.
+.TP
+.B \f[I]version\f[R]
+API version requested by application.
+.TP
+.B \f[I]name\f[R]
+Well\-known name of the library object to open.
+.TP
+.B \f[I]attr\f[R]
+Optional attributes of object to open.
+.TP
+.B \f[I]attr_len\f[R]
+Size of any attribute structure passed to fi_open.
+Should be 0 if no attributes are give.
+.TP
+.B \f[I]fid\f[R]
+Returned fabric identifier for opened object.
+.SH DESCRIPTION
+.PP
+A fabric provider implements the application facing software interfaces
+needed to access network specific protocols, drivers, and hardware.
+The interfaces and structures defined by this man page are exported by
+the libfabric library, but are targeted for provider implementations,
+rather than for direct use by most applications.
+.PP
+Integrated providers are those built directly into the libfabric library
+itself.
+External providers are loaded dynamically by libfabric at initialization
+time.
+External providers must be in a standard library path or in the
+libfabric library search path as specified by environment variable.
+Additionally, external providers must be named with the suffix
+\[lq]\-fi.so\[rq] at the end of the name.
+.PP
+Named objects are special purpose resources which are accessible
+directly to applications.
+They may be used to enhance or modify the behavior of library core.
+For details, see the fi_open call below.
+.SS fi_prov_ini
+.PP
+This entry point must be defined by external providers.
+On loading, libfabric will invoke fi_prov_ini() to retrieve the
+provider\[cq]s fi_provider structure.
+Additional interactions between the libfabric core and the provider will
+be through the interfaces defined by that struct.
+.SS fi_param_define / fi_param_get
+.PP
+TODO
+.SS fi_log_enabled / fi_log
+.PP
+TODO
+.SS fi_open
+.PP
+Open a library resource using a well\-known name.
+This feature allows applications and providers a mechanism which can be
+used to modify or enhance core library services and behavior.
+The details are specific based on the requested object name.
+Most applications will not need this level of control.
+.PP
+The library API version known to the application should be provided
+through the version parameter.
+The use of attributes is object dependent.
+If required, attributes should be provided through the attr parameter,
+with attr_len set to the size of the referenced attribute structure.
+The following is a list of published names, along with descriptions of
+the service or resource to which they correspond.
+.TP
+.B \f[I]mr_cache\f[R]
+The mr_cache object references the internal memory registration cache
+used by the different providers.
+Additional information on the cache is available in the
+\f[C]fi_mr(3)\f[R] man page.
+.SS fi_export_fid / fi_import_fid
+.PP
+Generally, fabric objects are allocated and managed entirely by a single
+provider.
+Typically only the application facing software interfaces of a fabric
+object are defined, for example, the message or tagged operations of an
+endpoint.
+The fi_export_fid and fi_import_fid calls provide a a mechanism by which
+provider facing APIs may be accessed.
+This allows the creation of fid objects that are shareable between
+providers, or for library plug\-in services.
+The ability to export a shareable object is object and provider
+implementation dependent.
+.PP
+Shareable fids typically contain at least 3 main components: a base fid,
+a set of exporter defined ops, and a set of importer defined ops.
+.SH NOTES
+.PP
+TODO
+.SH PROVIDER INTERFACE
+.PP
+The fi_provider structure defines entry points for the libfabric core to
+use to access the provider.
+All other calls into a provider are through function pointers associated
+with allocated objects.
+.IP
+.nf
+\f[C]
+struct fi_provider {
+    uint32_t version;
+    uint32_t fi_version;
+    struct fi_context context;
+    const char *name;
+    int (*getinfo)(uint32_t version, const char *node, const char *service,
+            uint64_t flags, const struct fi_info *hints,
+            struct fi_info **info);
+    int (*fabric)(struct fi_fabric_attr *attr, struct fid_fabric **fabric,
+            void *context);
+    void    (*cleanup)(void);
+};
+\f[R]
+.fi
+.SS version
+.PP
+The provider version.
+For providers integrated with the library, this is often the same as the
+library version.
+.SS fi_version
+.PP
+The library interface version that the provider was implemented against.
+The provider\[cq]s fi_version must be greater than or equal to an
+application\[cq]s requested api version for the application to use the
+provider.
+It is a provider\[cq]s responsibility to support older versions of the
+api if it wishes to supports legacy applications.
+For integrated providers
+.SS TODO
+.SH RETURN VALUE
+.PP
+Returns FI_SUCCESS on success.
+On error, a negative value corresponding to fabric errno is returned.
+Fabric errno values are defined in \f[C]rdma/fi_errno.h\f[R].
+.SH ERRORS
+.SH SEE ALSO
+.PP
+\f[C]fabric\f[R](7), \f[C]fi_getinfo\f[R](3) \f[C]fi_mr\f[R](3),
+.SH AUTHORS
+OpenFabrics.