1fi_provider(3)                 Libfabric v1.14.0                fi_provider(3)
2
3
4

NAME

6       fi_prov_ini - External provider entry point
7
8       fi_param_define / fi_param_get
9              Register  and  retrieve environment variables with the libfabric
10              core
11
12       fi_log_enabled / fi_log_ready / fi_log
13              Control and output debug logging information.
14
15       fi_open / fi_close
16              Open a named library object
17
18       fi_export_fid / fi_import_fid
19              Share a fabric object between different providers or resources
20

SYNOPSIS

22              #include <rdma/fabric.h>
23              #include <rdma/prov/fi_prov.h>
24
25              struct fi_provider* fi_prov_ini(void);
26
27              int fi_param_define(const struct fi_provider *provider, const char *param_name,
28                  enum fi_param_type type, const char *help_string_fmt, ...);
29
30              int fi_param_get_str(struct fi_provider *provider, const char *param_name,
31                  char **value);
32
33              int fi_param_get_int(struct fi_provider *provider, const char *param_name,
34                  int *value);
35
36              int fi_param_get_bool(struct fi_provider *provider, const char *param_name,
37                  int *value);
38
39              int fi_param_get_size_t(struct fi_provider *provider, const char *param_name,
40                  size_t *value);
41
42              #include <rdma/fabric.h>
43              #include <rdma/prov/fi_prov.h>
44              #include <rdma/prov/fi_log.h>
45
46              int fi_log_enabled(const struct fi_provider *prov, enum fi_log_level level,
47                  enum fi_log_subsys subsys);
48
49              int fi_log_ready(const struct fi_provider *prov, enum fi_log_level level,
50                  enum fi_log_subsys subsys, uint64_t *showtime);
51
52              void fi_log(const struct fi_provider *prov, enum fi_log_level level,
53                  enum fi_log_subsys subsys, const char *func, int line,
54                  const char *fmt, ...);
55
56              #include <rdma/fabric.h>
57
58              int fi_open(uint32_t version, const char *name, void *attr,
59                  size_t attr_len, uint64_t flags, struct fid **fid, void *context);
60
61              int fi_close(struct fid *fid);
62
63              #include <rdma/fabric.h>
64              #include <rdma/fi_ext.h>
65
66              int fi_export_fid(struct fid *fid, uint64_t flags,
67                  struct fid **expfid, void *context);
68
69              int fi_import_fid(struct fid *fid, struct fid *expfid, uint64_t flags);
70

ARGUMENTS

72       provider
73              Reference to the provider.
74
75       version
76              API version requested by application.
77
78       name   Well-known name of the library object to open.
79
80       attr   Optional attributes of object to open.
81
82       attr_len
83              Size of any attribute structure passed to fi_open.  Should be  0
84              if no attributes are give.
85
86       fid    Returned fabric identifier for opened object.
87

DESCRIPTION

89       A fabric provider implements the application facing software interfaces
90       needed to access network specific  protocols,  drivers,  and  hardware.
91       The  interfaces and structures defined by this man page are exported by
92       the libfabric library, but are targeted for  provider  implementations,
93       rather than for direct use by most applications.
94
95       Integrated  providers  are  those built directly into the libfabric li‐
96       brary itself.  External providers are loaded dynamically  by  libfabric
97       at  initialization  time.  External providers must be in a standard li‐
98       brary path or in the libfabric library search path as specified by  en‐
99       vironment  variable.   Additionally,  external  providers must be named
100       with the suffix “-fi.so” at the end of the name.
101
102       Named objects are special purpose resources which  are  accessible  di‐
103       rectly  to applications.  They may be used to enhance or modify the be‐
104       havior of library core.  For details, see the fi_open call below.
105
106   fi_prov_ini
107       This entry point must be defined by external  providers.   On  loading,
108       libfabric   will   invoke  fi_prov_ini()  to  retrieve  the  provider’s
109       fi_provider structure.  Additional interactions between  the  libfabric
110       core  and  the  provider will be through the interfaces defined by that
111       struct.
112
113   fi_param_define
114       Defines a configuration parameter for use by a specified provider.  The
115       help_string and param_name arguments must be non-NULL, help_string must
116       additionally be non-empty.  They are copied internally and may be freed
117       after calling fi_param_define.
118
119   fi_param_get
120       Gets  the  value  of a configuration parameter previously defined using
121       fi_param_define().  The value comes from the environment variable  name
122       of the form FI__, all converted to upper case.
123
124       If  the  parameter  was  previously  defined  and the user set a value,
125       FI_SUCCESS is returned and (*value) points to the retrieved value.
126
127       If the parameter name was previously defined, but the user did not  set
128       a  value,  -FI_ENODATA  is  returned  and  the value of (*value) is un‐
129       changed.
130
131       If the parameter name was not previously defined via fi_param_define(),
132       -FI_ENOENT will be returned and the value of (*value) is unchanged.
133
134       If  the  value  in the environment is not valid for the parameter type,
135       -FI_EINVAL will be returned and the value of (*value) is unchanged.
136
137   fi_log_enabled / fi_log_ready / fi_log
138       These  functions  control  debug  and  informational  logging   output.
139       Providers  typically  access these functions through the FI_LOG and re‐
140       lated macros in fi_log.h and do not call these function directly.
141
142   fi_open
143       Open a library resource using a well-known name.  This  feature  allows
144       applications  and  providers a mechanism which can be used to modify or
145       enhance core library services and behavior.  The details  are  specific
146       based  on  the  requested object name.  Most applications will not need
147       this level of control.
148
149       The library API version known to the  application  should  be  provided
150       through  the version parameter.  The use of attributes is object depen‐
151       dent.  If required, attributes should be provided through the attr  pa‐
152       rameter,  with  attr_len  set  to  the size of the referenced attribute
153       structure.  The following is a list of published names, along with  de‐
154       scriptions of the service or resource to which they correspond.
155
156       mr_cache
157              The  mr_cache object references the internal memory registration
158              cache used by the different providers.   Additional  information
159              on the cache is available in the fi_mr(3) man page.
160
161   fi_export_fid / fi_import_fid
162       Generally,  fabric objects are allocated and managed entirely by a sin‐
163       gle provider.  Typically only the application  facing  software  inter‐
164       faces  of  a  fabric  object  are  defined, for example, the message or
165       tagged operations of an endpoint.  The fi_export_fid and  fi_import_fid
166       calls  provide  a  a mechanism by which provider facing APIs may be ac‐
167       cessed.  This allows the creation of fid objects that are shareable be‐
168       tween  providers,  or for library plug-in services.  The ability to ex‐
169       port a shareable object is object and  provider  implementation  depen‐
170       dent.
171
172       Shareable  fids  typically  contain  at least 3 main components: a base
173       fid, a set of exporter defined ops, and a set of importer defined ops.
174

NOTES

176       TODO
177

PROVIDER INTERFACE

179       The fi_provider structure defines entry points for the  libfabric  core
180       to  use  to  access  the provider.  All other calls into a provider are
181       through function pointers associated with allocated objects.
182
183              struct fi_provider {
184                  uint32_t version;
185                  uint32_t fi_version;
186                  struct fi_context context;
187                  const char *name;
188                  int (*getinfo)(uint32_t version, const char *node, const char *service,
189                          uint64_t flags, const struct fi_info *hints,
190                          struct fi_info **info);
191                  int (*fabric)(struct fi_fabric_attr *attr, struct fid_fabric **fabric,
192                          void *context);
193                  void    (*cleanup)(void);
194              };
195
196   version
197       The provider version.  For providers integrated with the library,  this
198       is often the same as the library version.
199
200   fi_version
201       The  library  interface  version  that  the  provider  was  implemented
202       against.  The provider’s fi_version must be greater than or equal to an
203       application’s  requested  api  version  for  the application to use the
204       provider.  It is a provider’s responsibility to support older  versions
205       of the api if it wishes to supports legacy applications.  For integrat‐
206       ed providers
207
208   TODO

RETURN VALUE

210       Returns FI_SUCCESS on success.  On error, a negative value  correspond‐
211       ing  to  fabric  errno is returned.  Fabric errno values are defined in
212       rdma/fi_errno.h.
213

ERRORS

SEE ALSO

216       fabric(7), fi_getinfo(3) fi_mr(3),
217

AUTHORS

219       OpenFabrics.
220
221
222
223Libfabric Programmer’s Manual     2021-09-22                    fi_provider(3)
Impressum