1fi_fabric(3) Libfabric v1.17.0 fi_fabric(3)
2
6 fi_fabric - Fabric network operations
7 fi_fabric / fi_close
9 Open / close a fabric network
10 fi_tostr / fi_tostr_r
12 Convert fabric attributes, flags, and capabilities to printable
13 string
14
16 #include <rdma/fabric.h>
17 int fi_fabric(struct fi_fabric_attr *attr,
19 struct fid_fabric **fabric, void *context);
20 int fi_close(struct fid *fabric);
22 char * fi_tostr(const void *data, enum fi_type datatype);
24 char * fi_tostr(char *buf, size_t len, const void *data,
26 enum fi_type datatype);
27
29 attr Attributes of fabric to open.
30 fabric Fabric network
32 context
34 User specified context associated with the opened object. This
35 context is returned as part of any associated asynchronous
36 event.
37 buf Output buffer to write string.
39 len Size in bytes of memory referenced by buf.
41 data Input data to convert into a string. The format of data is de‐
43 termined by the datatype parameter.
44 datatype
46 Indicates the data to convert to a printable string.
47
49 A fabric identifier is used to reference opened fabric resources and
50 library related objects.
51 The fabric network represents a collection of hardware and software re‐
53 sources that access a single physical or virtual network. All network
54 ports on a system that can communicate with each other through their
55 attached networks belong to the same fabric. A fabric network shares
56 network addresses and can span multiple providers. An application must
57 open a fabric network prior to allocating other network resources, such
58 as communication endpoints.
59 fi_fabric
61 Opens a fabric network provider. The attributes of the fabric provider
62 are specified through the open call, and may be obtained by calling
63 fi_getinfo.
64 fi_close
66 The fi_close call is used to release all resources associated with a
67 fabric object. All items associated with the opened fabric must be re‐
68 leased prior to calling fi_close.
69 fi_tostr / fi_tostr_r
71 Converts fabric interface attributes, capabilities, flags, and enum
72 values into a printable string. The data parameter accepts a pointer
73 to the attribute or value(s) to display, with the datatype parameter
74 indicating the type of data referenced by the data parameter. Valid
75 values for the datatype are listed below, along with the corresponding
76 datatype or field value.
77 FI_TYPE_INFO
79 struct fi_info, including all substructures and fields
80 FI_TYPE_EP_TYPE
82 struct fi_info::type field
83 FI_TYPE_EP_CAP
85 struct fi_info::ep_cap field
86 FI_TYPE_OP_FLAGS
88 struct fi_info::op_flags field, or general uint64_t flags
89 FI_TYPE_ADDR_FORMAT
91 struct fi_info::addr_format field
92 FI_TYPE_TX_ATTR
94 struct fi_tx_attr
95 FI_TYPE_RX_ATTR
97 struct fi_rx_attr
98 FI_TYPE_EP_ATTR
100 struct fi_ep_attr
101 FI_TYPE_DOMAIN_ATTR
103 struct fi_domain_attr
104 FI_TYPE_FABRIC_ATTR
106 struct fi_fabric_attr
107 FI_TYPE_THREADING
109 enum fi_threading
110 FI_TYPE_PROGRESS
112 enum fi_progress
113 FI_TYPE_PROTOCOL
115 struct fi_ep_attr::protocol field
116 FI_TYPE_MSG_ORDER
118 struct fi_ep_attr::msg_order field
119 FI_TYPE_MODE
121 struct fi_info::mode field
122 FI_TYPE_AV_TYPE
124 enum fi_av_type
125 FI_TYPE_ATOMIC_TYPE
127 enum fi_datatype
128 FI_TYPE_ATOMIC_OP
130 enum fi_op
131 FI_TYPE_VERSION
133 Returns the library version of libfabric in string form. The
134 data parameter is ignored.
135 FI_TYPE_EQ_EVENT
137 uint32_t event parameter returned from fi_eq_read(). See
138 fi_eq(3) for a list of known values.
139 FI_TYPE_CQ_EVENT_FLAGS
141 uint64_t flags field in fi_cq_xxx_entry structures. See
142 fi_cq(3) for valid flags.
143 FI_TYPE_MR_MODE
145 struct fi_domain_attr::mr_mode flags
146 FI_TYPE_OP_TYPE
148 enum fi_op_type
149 FI_TYPE_FID
151 struct fid *
152 FI_TYPE_HMEM_IFACE
154 enum fi_hmem_iface *
155 FI_TYPE_CQ_FORMAT
157 enum fi_cq_format
158 FI_TYPE_LOG_LEVEL
160 enum fi_log_level
161 FI_TYPE_LOG_SUBSYS
163 enum fi_log_subsys
164 fi_tostr() will return a pointer to an internal libfabric buffer that
166 should not be modified, and will be overwritten the next time
167 fi_tostr() is invoked. fi_tostr() is not thread safe.
168 The fi_tostr_r() function is a re-entrant and thread safe version of
170 fi_tostr(). It writes the string into a buffer provided by the caller.
171 fi_tostr_r() returns the start of the caller’s buffer.
172
174 The following resources are associated with fabric domains: access do‐
175 mains, passive endpoints, and CM event queues.
176
178 The fi_fabric_attr structure defines the set of attributes associated
179 with a fabric and a fabric provider.
180 struct fi_fabric_attr {
182 struct fid_fabric *fabric;
183 char *name;
184 char *prov_name;
185 uint32_t prov_version;
186 uint32_t api_version;
187 };
188 fabric
190 On input to fi_getinfo, a user may set this to an opened fabric in‐
191 stance to restrict output to the given fabric. On output from fi_get‐
192 info, if no fabric was specified, but the user has an opened instance
193 of the named fabric, this will reference the first opened instance. If
194 no instance has been opened, this field will be NULL.
195 The fabric instance returned by fi_getinfo should only be considered
197 valid if the application does not close any fabric instances from an‐
198 other thread while fi_getinfo is being processed.
199 name
201 A fabric identifier.
202 prov_name - Provider Name
204 The name of the underlying fabric provider.
205 To request an utility provider layered over a specific core provider,
207 both the provider names have to be specified using “;” as delimiter.
208 e.g. “ofi_rxm;verbs” or “verbs;ofi_rxm”
210 For debugging and administrative purposes, environment variables can be
212 used to control which fabric providers will be registered with libfab‐
213 ric. Specifying “FI_PROVIDER=foo,bar” will allow any providers with
214 the names “foo” or “bar” to be registered. Similarly, specifying
215 “FI_PROVIDER=^foo,bar” will prevent any providers with the names “foo”
216 or “bar” from being registered. Providers which are not registered
217 will not appear in fi_getinfo results. Applications which need a spe‐
218 cific set of providers should implement their own filtering of fi_get‐
219 info’s results rather than relying on these environment variables in a
220 production setting.
221 prov_version - Provider Version
223 Version information for the fabric provider, in a major.minor format.
224 The use of the FI_MAJOR() and FI_MINOR() version macros may be used to
225 extract the major and minor version data. See fi_version(3).
226 In case of an utility provider layered over a core provider, the ver‐
228 sion would always refer to that of the utility provider.
229 api_version
231 The interface version requested by the application. This value corre‐
232 sponds to the version parameter passed into fi_getinfo(3).
233
235 Returns FI_SUCCESS on success. On error, a negative value correspond‐
236 ing to fabric errno is returned. Fabric errno values are defined in
237 rdma/fi_errno.h.
238
241 fabric(7), fi_getinfo(3), fi_domain(3), fi_eq(3), fi_endpoint(3)
242
244 OpenFabrics.
245Libfabric Programmer’s Manual 2022-12-11 fi_fabric(3)