1fi_fabric(3)                   Libfabric v1.17.0                  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_TYPE_LOG_LEVEL
160              enum fi_log_level
161
162       FI_TYPE_LOG_SUBSYS
163              enum fi_log_subsys
164
165       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
169       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

NOTES

174       The following resources are associated with fabric domains: access  do‐
175       mains, passive endpoints, and CM event queues.
176

FABRIC ATTRIBUTES

178       The  fi_fabric_attr  structure defines the set of attributes associated
179       with a fabric and a fabric provider.
180
181              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
189   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
196       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
200   name
201       A fabric identifier.
202
203   prov_name - Provider Name
204       The name of the underlying fabric provider.
205
206       To request an utility provider layered over a specific  core  provider,
207       both the provider names have to be specified using “;” as delimiter.
208
209       e.g. “ofi_rxm;verbs” or “verbs;ofi_rxm”
210
211       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
222   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
227       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
230   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

RETURN VALUE

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

ERRORS

SEE ALSO

241       fabric(7), fi_getinfo(3), fi_domain(3), fi_eq(3), fi_endpoint(3)
242

AUTHORS

244       OpenFabrics.
245
246
247
248Libfabric Programmer’s Manual     2022-12-11                      fi_fabric(3)
Impressum