From 86c391cb0c924f15bf047a3be48c5c88544cc0c7 Mon Sep 17 00:00:00 2001 From: OFIWG Bot Date: Sat, 5 Jun 2021 02:22:28 +0000 Subject: [PATCH] Updated nroff-generated man pages Signed-off-by: OFIWG Bot --- man/man3/fi_fabric.3 | 23 +++-- man/man3/fi_mr.3 | 10 +- man/man3/fi_provider.3 | 226 ++++++++++++++++++++++++++++++++++++++++- 3 files changed, 248 insertions(+), 11 deletions(-) diff --git a/man/man3/fi_fabric.3 b/man/man3/fi_fabric.3 index 79800c35f4b..44429b6b76e 100644 --- a/man/man3/fi_fabric.3 +++ b/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 diff --git a/man/man3/fi_mr.3 b/man/man3/fi_mr.3 index f96398e9a78..c44d1ee17a8 100644 --- a/man/man3/fi_mr.3 +++ b/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), diff --git a/man/man3/fi_provider.3 b/man/man3/fi_provider.3 index f72423bcc56..bf7f4a5a162 100644 --- a/man/man3/fi_provider.3 +++ b/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 +#include + +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 +#include +#include + +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 + +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 +#include + +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.