1fi_fabric(3) Libfabric v1.12.0rc1 fi_fabric(3)
2
6 fi_fabric - Fabric domain operations
7 fi_fabric / fi_close
9 Open / close a fabric domain
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 domain
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 domain represents a collection of hardware and software re‐
50 sources that access a single physical or virtual network. All network
51 ports on a system that can communicate with each other through their
52 attached networks belong to the same fabric domain. A fabric domain
53 shares network addresses and can span multiple providers.
54 fi_fabric
56 Opens a fabric provider. The attributes of the fabric provider are
57 specified through the open call, and may be obtained by calling fi_get‐
58 info.
59 fi_close
61 The fi_close call is used to release all resources associated with a
62 fabric domain or interface. All items associated with the opened fab‐
63 ric must be released prior to calling fi_close.
64 fi_tostr / fi_tostr_r
66 Converts fabric interface attributes, capabilities, flags, and enum
67 values into a printable string. The data parameter accepts a pointer
68 to the attribute or value(s) to display, with the datatype parameter
69 indicating the type of data referenced by the data parameter. Valid
70 values for the datatype are listed below, along with the corresponding
71 datatype or field value.
72 FI_TYPE_INFO
74 struct fi_info, including all substructures and fields
75 FI_TYPE_EP_TYPE
77 struct fi_info::type field
78 FI_TYPE_EP_CAP
80 struct fi_info::ep_cap field
81 FI_TYPE_OP_FLAGS
83 struct fi_info::op_flags field, or general uint64_t flags
84 FI_TYPE_ADDR_FORMAT
86 struct fi_info::addr_format field
87 FI_TYPE_TX_ATTR
89 struct fi_tx_attr
90 FI_TYPE_RX_ATTR
92 struct fi_rx_attr
93 FI_TYPE_EP_ATTR
95 struct fi_ep_attr
96 FI_TYPE_DOMAIN_ATTR
98 struct fi_domain_attr
99 FI_TYPE_FABRIC_ATTR
101 struct fi_fabric_attr
102 FI_TYPE_THREADING
104 enum fi_threading
105 FI_TYPE_PROGRESS
107 enum fi_progress
108 FI_TYPE_PROTOCOL
110 struct fi_ep_attr::protocol field
111 FI_TYPE_MSG_ORDER
113 struct fi_ep_attr::msg_order field
114 FI_TYPE_MODE
116 struct fi_info::mode field
117 FI_TYPE_AV_TYPE
119 enum fi_av_type
120 FI_TYPE_ATOMIC_TYPE
122 enum fi_datatype
123 FI_TYPE_ATOMIC_OP
125 enum fi_op
126 FI_TYPE_VERSION
128 Returns the library version of libfabric in string form. The
129 data parameter is ignored.
130 FI_TYPE_EQ_EVENT
132 uint32_t event parameter returned from fi_eq_read(). See
133 fi_eq(3) for a list of known values.
134 FI_TYPE_CQ_EVENT_FLAGS
136 uint64_t flags field in fi_cq_xxx_entry structures. See
137 fi_cq(3) for valid flags.
138 FI_TYPE_MR_MODE
140 struct fi_domain_attr::mr_mode flags
141 FI_TYPE_OP_TYPE
143 enum fi_op_type
144 FI_TYPE_FID
146 struct fid *
147 FI_TYPE_HMEM_IFACE
149 enum fi_hmem_iface *
150 fi_tostr() will return a pointer to an internal libfabric buffer that
152 should not be modified, and will be overwritten the next time
153 fi_tostr() is invoked. fi_tostr() is not thread safe.
154 The fi_tostr_r() function is a re-entrant and thread safe version of
156 fi_tostr(). It writes the string into a buffer provided by the caller.
157 fi_tostr_r() returns the start of the caller's buffer.
158
160 The following resources are associated with fabric domains: access do‐
161 mains, passive endpoints, and CM event queues.
162
164 The fi_fabric_attr structure defines the set of attributes associated
165 with a fabric and a fabric provider.
166 struct fi_fabric_attr {
168 struct fid_fabric *fabric;
169 char *name;
170 char *prov_name;
171 uint32_t prov_version;
172 uint32_t api_version;
173 };
174 fabric
176 On input to fi_getinfo, a user may set this to an opened fabric in‐
177 stance to restrict output to the given fabric. On output from fi_get‐
178 info, if no fabric was specified, but the user has an opened instance
179 of the named fabric, this will reference the first opened instance. If
180 no instance has been opened, this field will be NULL.
181 The fabric instance returned by fi_getinfo should only be considered
183 valid if the application does not close any fabric instances from an‐
184 other thread while fi_getinfo is being processed.
185 name
187 A fabric identifier.
188 prov_name - Provider Name
190 The name of the underlying fabric provider.
191 To request an utility provider layered over a specific core provider,
193 both the provider names have to be specified using ";" as delimiter.
194 e.g. "ofi_rxm;verbs" or "verbs;ofi_rxm"
196 For debugging and administrative purposes, environment variables can be
198 used to control which fabric providers will be registered with libfab‐
199 ric. Specifying "FI_PROVIDER=foo,bar" will allow any providers with
200 the names "foo" or "bar" to be registered. Similarly, specifying
201 "FI_PROVIDER=^foo,bar" will prevent any providers with the names "foo"
202 or "bar" from being registered. Providers which are not registered
203 will not appear in fi_getinfo results. Applications which need a spe‐
204 cific set of providers should implement their own filtering of fi_get‐
205 info's results rather than relying on these environment variables in a
206 production setting.
207 prov_version - Provider Version
209 Version information for the fabric provider, in a major.minor format.
210 The use of the FI_MAJOR() and FI_MINOR() version macros may be used to
211 extract the major and minor version data. See fi_version(3).
212 In case of an utility provider layered over a core provider, the ver‐
214 sion would always refer to that of the utility provider.
215 api_version
217 The interface version requested by the application. This value corre‐
218 sponds to the version parameter passed into fi_getinfo(3).
219
221 Returns FI_SUCCESS on success. On error, a negative value correspond‐
222 ing to fabric errno is returned. Fabric errno values are defined in
223 rdma/fi_errno.h.
224
227 fabric(7), fi_getinfo(3), fi_domain(3), fi_eq(3), fi_endpoint(3)
228
230 OpenFabrics.
231Libfabric Programmer's Manual 2020-10-20 fi_fabric(3)