1fi_provider(3)                 Libfabric v1.17.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_import / fi_close
16              Open and import a named library object
17
18       fi_import_log
19              Import new logging callbacks
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              static inline int fi_import(uint32_t version, const char *name, void *attr,
62                              size_t attr_len, uint64_t flags, struct fid *fid,
63                              void *context);
64
65              int fi_close(struct fid *fid);
66
67              #include <rdma/fabric.h>
68              #include <rdma/fi_ext.h>
69
70              static inline int fi_import_log(uint32_t version, uint64_t flags,
71                              struct fid_logging *log_fid);
72

ARGUMENTS

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

DESCRIPTION

91       A fabric provider implements the application facing software interfaces
92       needed to access network specific  protocols,  drivers,  and  hardware.
93       The  interfaces and structures defined by this man page are exported by
94       the libfabric library, but are targeted for  provider  implementations,
95       rather than for direct use by most applications.
96
97       Integrated  providers  are  those built directly into the libfabric li‐
98       brary itself.  External providers are loaded dynamically  by  libfabric
99       at  initialization  time.  External providers must be in a standard li‐
100       brary path or in the libfabric library search path as specified by  en‐
101       vironment  variable.   Additionally,  external  providers must be named
102       with the suffix “-fi.so” at the end of the name.
103
104       Named objects are special purpose resources which  are  accessible  di‐
105       rectly  to applications.  They may be used to enhance or modify the be‐
106       havior of library core.  For details, see the fi_open call below.
107
108   fi_prov_ini
109       This entry point must be defined by external  providers.   On  loading,
110       libfabric   will   invoke  fi_prov_ini()  to  retrieve  the  provider’s
111       fi_provider structure.  Additional interactions between  the  libfabric
112       core  and  the  provider will be through the interfaces defined by that
113       struct.
114
115   fi_param_define
116       Defines a configuration parameter for use by a specified provider.  The
117       help_string and param_name arguments must be non-NULL, help_string must
118       additionally be non-empty.  They are copied internally and may be freed
119       after calling fi_param_define.
120
121   fi_param_get
122       Gets  the  value  of a configuration parameter previously defined using
123       fi_param_define().  The value comes from the environment variable  name
124       of the form FI__, all converted to upper case.
125
126       If  the  parameter  was  previously  defined  and the user set a value,
127       FI_SUCCESS is returned and (*value) points to the retrieved value.
128
129       If the parameter name was previously defined, but the user did not  set
130       a  value,  -FI_ENODATA  is  returned  and  the value of (*value) is un‐
131       changed.
132
133       If the parameter name was not previously defined via fi_param_define(),
134       -FI_ENOENT will be returned and the value of (*value) is unchanged.
135
136       If  the  value  in the environment is not valid for the parameter type,
137       -FI_EINVAL will be returned and the value of (*value) is unchanged.
138
139   fi_log_enabled / fi_log_ready / fi_log
140       These  functions  control  debug  and  informational  logging   output.
141       Providers  typically  access these functions through the FI_LOG and re‐
142       lated macros in fi_log.h and do not call these function directly.
143
144   fi_open
145       Open a library resource using a well-known name.  This  feature  allows
146       applications  and  providers a mechanism which can be used to modify or
147       enhance core library services and behavior.  The details  are  specific
148       based  on  the  requested object name.  Most applications will not need
149       this level of control.
150
151       The library API version known to the  application  should  be  provided
152       through  the version parameter.  The use of attributes is object depen‐
153       dent.  If required, attributes should be provided through the attr  pa‐
154       rameter,  with  attr_len  set  to  the size of the referenced attribute
155       structure.  The following is a list of published names, along with  de‐
156       scriptions of the service or resource to which they correspond.
157
158       mr_cache
159              The  mr_cache object references the internal memory registration
160              cache used by the different providers.   Additional  information
161              on the cache is available in the fi_mr(3) man page.
162
163       logging
164              The  logging  object  references  the internal logging subsystem
165              used by the different providers.  Once  opened,  custom  logging
166              callbacks  may  be  installed.  Can be opened only once and only
167              the last import is used if imported multiple times.
168
169   fi_import
170       This helper function is a combination of fi_open and fi_import_fid.  It
171       may  be used to import a fabric object created and owned by the libfab‐
172       ric user.  This allows the upper level libraries or the application  to
173       override or define low-level libfabric behavior.
174
175   fi_import_log
176       Helper  function  to  override the low-level libfabric’s logging system
177       with new callback functions.
178
179              struct fi_ops_log {
180                  size_t size;
181                  int (*enabled)(const struct fi_provider *prov, enum fi_log_level level,
182                             enum fi_log_subsys subsys, uint64_t flags);
183                  int (*ready)(const struct fi_provider *prov, enum fi_log_level level,
184                           enum fi_log_subsys subsys, uint64_t flags, uint64_t *showtime);
185                  void (*log)(const struct fi_provider *prov, enum fi_log_level level,
186                          enum fi_log_subsys subsys, const char *func, int line,
187                          const char *msg);
188              };
189
190              struct fid_logging {
191                  struct fid          fid;
192                  struct fi_ops_log   *ops;
193              };
194

PROVIDER INTERFACE

196       The fi_provider structure defines entry points for the  libfabric  core
197       to  use  to  access  the provider.  All other calls into a provider are
198       through function pointers associated with allocated objects.
199
200              struct fi_provider {
201                  uint32_t version;
202                  uint32_t fi_version;
203                  struct fi_context context;
204                  const char *name;
205                  int (*getinfo)(uint32_t version, const char *node, const char *service,
206                          uint64_t flags, const struct fi_info *hints,
207                          struct fi_info **info);
208                  int (*fabric)(struct fi_fabric_attr *attr, struct fid_fabric **fabric,
209                          void *context);
210                  void    (*cleanup)(void);
211              };
212
213   version
214       The provider version.  For providers integrated with the library,  this
215       is often the same as the library version.
216
217   fi_version
218       The  library  interface  version  that  the  provider  was  implemented
219       against.  The provider’s fi_version must be greater than or equal to an
220       application’s  requested  api  version  for  the application to use the
221       provider.  It is a provider’s responsibility to support older  versions
222       of the api if it wishes to supports legacy applications.  For integrat‐
223       ed providers
224

RETURN VALUE

226       Returns FI_SUCCESS on success.  On error, a negative value  correspond‐
227       ing  to  fabric  errno is returned.  Fabric errno values are defined in
228       rdma/fi_errno.h.
229

SEE ALSO

231       fabric(7), fi_getinfo(3) fi_mr(3),
232

AUTHORS

234       OpenFabrics.
235
236
237
238Libfabric Programmer’s Manual     2022-12-11                    fi_provider(3)
Impressum