1fi_fabric(3)                   Libfabric v1.15.1                  fi_fabric(3)
2
3
4

NAME

6       fi_fabric - Fabric network operations
7
8       fi_fabric / fi_close
9              Open / close a fabric network
10
11       fi_tostr / fi_tostr_r
12              Convert  fabric attributes, flags, and capabilities to printable
13              string
14

SYNOPSIS

16              #include <rdma/fabric.h>
17
18              int fi_fabric(struct fi_fabric_attr *attr,
19                  struct fid_fabric **fabric, void *context);
20
21              int fi_close(struct fid *fabric);
22
23              char * fi_tostr(const void *data, enum fi_type datatype);
24
25              char * fi_tostr(char *buf, size_t len, const void *data,
26                  enum fi_type datatype);
27

ARGUMENTS

29       attr   Attributes of fabric to open.
30
31       fabric Fabric network
32
33       context
34              User specified context associated with the opened object.   This
35              context  is  returned  as  part  of  any associated asynchronous
36              event.
37
38       buf    Output buffer to write string.
39
40       len    Size in bytes of memory referenced by buf.
41
42       data   Input data to convert into a string.  The format of data is  de‐
43              termined by the datatype parameter.
44
45       datatype
46              Indicates the data to convert to a printable string.
47

DESCRIPTION

49       A  fabric  identifier  is used to reference opened fabric resources and
50       library related objects.
51
52       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
60   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
65   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
70   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
78       FI_TYPE_INFO
79              struct fi_info, including all substructures and fields
80
81       FI_TYPE_EP_TYPE
82              struct fi_info::type field
83
84       FI_TYPE_EP_CAP
85              struct fi_info::ep_cap field
86
87       FI_TYPE_OP_FLAGS
88              struct fi_info::op_flags field, or general uint64_t flags
89
90       FI_TYPE_ADDR_FORMAT
91              struct fi_info::addr_format field
92
93       FI_TYPE_TX_ATTR
94              struct fi_tx_attr
95
96       FI_TYPE_RX_ATTR
97              struct fi_rx_attr
98
99       FI_TYPE_EP_ATTR
100              struct fi_ep_attr
101
102       FI_TYPE_DOMAIN_ATTR
103              struct fi_domain_attr
104
105       FI_TYPE_FABRIC_ATTR
106              struct fi_fabric_attr
107
108       FI_TYPE_THREADING
109              enum fi_threading
110
111       FI_TYPE_PROGRESS
112              enum fi_progress
113
114       FI_TYPE_PROTOCOL
115              struct fi_ep_attr::protocol field
116
117       FI_TYPE_MSG_ORDER
118              struct fi_ep_attr::msg_order field
119
120       FI_TYPE_MODE
121              struct fi_info::mode field
122
123       FI_TYPE_AV_TYPE
124              enum fi_av_type
125
126       FI_TYPE_ATOMIC_TYPE
127              enum fi_datatype
128
129       FI_TYPE_ATOMIC_OP
130              enum fi_op
131
132       FI_TYPE_VERSION
133              Returns  the  library  version of libfabric in string form.  The
134              data parameter is ignored.
135
136       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
140       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
144       FI_TYPE_MR_MODE
145              struct fi_domain_attr::mr_mode flags
146
147       FI_TYPE_OP_TYPE
148              enum fi_op_type
149
150       FI_TYPE_FID
151              struct fid *
152
153       FI_TYPE_HMEM_IFACE
154              enum fi_hmem_iface *
155
156       FI_TYPE_CQ_FORMAT
157              enum fi_cq_format
158
159       fi_tostr() will return a pointer to an internal libfabric  buffer  that
160       should  not  be  modified,  and  will  be  overwritten  the  next  time
161       fi_tostr() is invoked.  fi_tostr() is not thread safe.
162
163       The fi_tostr_r() function is a re-entrant and thread  safe  version  of
164       fi_tostr().  It writes the string into a buffer provided by the caller.
165       fi_tostr_r() returns the start of the caller’s buffer.
166

NOTES

168       The following resources are associated with fabric domains: access  do‐
169       mains, passive endpoints, and CM event queues.
170

FABRIC ATTRIBUTES

172       The  fi_fabric_attr  structure defines the set of attributes associated
173       with a fabric and a fabric provider.
174
175              struct fi_fabric_attr {
176                  struct fid_fabric *fabric;
177                  char              *name;
178                  char              *prov_name;
179                  uint32_t          prov_version;
180                  uint32_t          api_version;
181              };
182
183   fabric
184       On input to fi_getinfo, a user may set this to  an  opened  fabric  in‐
185       stance  to restrict output to the given fabric.  On output from fi_get‐
186       info, if no fabric was specified, but the user has an  opened  instance
187       of the named fabric, this will reference the first opened instance.  If
188       no instance has been opened, this field will be NULL.
189
190       The fabric instance returned by fi_getinfo should  only  be  considered
191       valid  if  the application does not close any fabric instances from an‐
192       other thread while fi_getinfo is being processed.
193
194   name
195       A fabric identifier.
196
197   prov_name - Provider Name
198       The name of the underlying fabric provider.
199
200       To request an utility provider layered over a specific  core  provider,
201       both the provider names have to be specified using “;” as delimiter.
202
203       e.g. “ofi_rxm;verbs” or “verbs;ofi_rxm”
204
205       For debugging and administrative purposes, environment variables can be
206       used to control which fabric providers will be registered with  libfab‐
207       ric.   Specifying  “FI_PROVIDER=foo,bar”  will allow any providers with
208       the names “foo” or  “bar”  to  be  registered.   Similarly,  specifying
209       “FI_PROVIDER=^foo,bar”  will prevent any providers with the names “foo”
210       or “bar” from being registered.  Providers  which  are  not  registered
211       will  not appear in fi_getinfo results.  Applications which need a spe‐
212       cific set of providers should implement their own filtering of  fi_get‐
213       info’s  results rather than relying on these environment variables in a
214       production setting.
215
216   prov_version - Provider Version
217       Version information for the fabric provider, in a  major.minor  format.
218       The  use of the FI_MAJOR() and FI_MINOR() version macros may be used to
219       extract the major and minor version data.  See fi_version(3).
220
221       In case of an utility provider layered over a core provider,  the  ver‐
222       sion would always refer to that of the utility provider.
223
224   api_version
225       The  interface version requested by the application.  This value corre‐
226       sponds to the version parameter passed into fi_getinfo(3).
227

RETURN VALUE

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

ERRORS

SEE ALSO

235       fabric(7), fi_getinfo(3), fi_domain(3), fi_eq(3), fi_endpoint(3)
236

AUTHORS

238       OpenFabrics.
239
240
241
242Libfabric Programmer’s Manual     2021-10-06                      fi_fabric(3)
Impressum