1fi_provider(3) Libfabric v1.18.1 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_import / fi_close
16 Open and import a named library object
17 fi_import_log
19 Import new logging callbacks
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 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 int fi_close(struct fid *fid);
66 #include <rdma/fabric.h>
68 #include <rdma/fi_ext.h>
69 static inline int fi_import_log(uint32_t version, uint64_t flags,
71 struct fid_logging *log_fid);
72
74 provider
75 Reference to the provider.
76 version
78 API version requested by application.
79 name Well-known name of the library object to open.
81 attr Optional attributes of object to open.
83 attr_len
85 Size of any attribute structure passed to fi_open. Should be 0
86 if no attributes are give.
87 fid Returned fabric identifier for opened object.
89
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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 fi_import_log
176 Helper function to override the low-level libfabric’s logging system
177 with new callback functions.
178 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 struct fid_logging {
191 struct fid fid;
192 struct fi_ops_log *ops;
193 };
194
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 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 version
214 The provider version. For providers integrated with the library, this
215 is often the same as the library version.
216 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
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
231 fabric(7), fi_getinfo(3) fi_mr(3),
232
234 OpenFabrics.
235Libfabric Programmer’s Manual 2022-12-09 fi_provider(3)