1fi_provider(3) Libfabric v1.14.0 fi_provider(3)
2
6 fi_prov_ini - External provider entry point
7 fi_param_define / fi_param_get
9 Register and retrieve environment variables with the libfabric
10 core
11 fi_log_enabled / fi_log_ready / fi_log
13 Control and output debug logging information.
14 fi_open / fi_close
16 Open a named library object
17 fi_export_fid / fi_import_fid
19 Share a fabric object between different providers or resources
20
22 #include <rdma/fabric.h>
23 #include <rdma/prov/fi_prov.h>
24 struct fi_provider* fi_prov_ini(void);
26 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 int fi_param_get_str(struct fi_provider *provider, const char *param_name,
31 char **value);
32 int fi_param_get_int(struct fi_provider *provider, const char *param_name,
34 int *value);
35 int fi_param_get_bool(struct fi_provider *provider, const char *param_name,
37 int *value);
38 int fi_param_get_size_t(struct fi_provider *provider, const char *param_name,
40 size_t *value);
41 #include <rdma/fabric.h>
43 #include <rdma/prov/fi_prov.h>
44 #include <rdma/prov/fi_log.h>
45 int fi_log_enabled(const struct fi_provider *prov, enum fi_log_level level,
47 enum fi_log_subsys subsys);
48 int fi_log_ready(const struct fi_provider *prov, enum fi_log_level level,
50 enum fi_log_subsys subsys, uint64_t *showtime);
51 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 #include <rdma/fabric.h>
57 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 int fi_close(struct fid *fid);
62 #include <rdma/fabric.h>
64 #include <rdma/fi_ext.h>
65 int fi_export_fid(struct fid *fid, uint64_t flags,
67 struct fid **expfid, void *context);
68 int fi_import_fid(struct fid *fid, struct fid *expfid, uint64_t flags);
70
72 provider
73 Reference to the provider.
74 version
76 API version requested by application.
77 name Well-known name of the library object to open.
79 attr Optional attributes of object to open.
81 attr_len
83 Size of any attribute structure passed to fi_open. Should be 0
84 if no attributes are give.
85 fid Returned fabric identifier for opened object.
87
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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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
176 TODO
177
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 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 version
197 The provider version. For providers integrated with the library, this
198 is often the same as the library version.
199 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 TODO
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
216 fabric(7), fi_getinfo(3) fi_mr(3),
217
219 OpenFabrics.
220Libfabric Programmer’s Manual 2021-09-22 fi_provider(3)