1fi_fabric(3)                 Libfabric v1.12.0rc1                 fi_fabric(3)
2
3
4

NAME

6       fi_fabric - Fabric domain operations
7
8       fi_fabric / fi_close
9              Open / close a fabric domain
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 domain
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  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
55   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
60   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
65   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
73       FI_TYPE_INFO
74              struct fi_info, including all substructures and fields
75
76       FI_TYPE_EP_TYPE
77              struct fi_info::type field
78
79       FI_TYPE_EP_CAP
80              struct fi_info::ep_cap field
81
82       FI_TYPE_OP_FLAGS
83              struct fi_info::op_flags field, or general uint64_t flags
84
85       FI_TYPE_ADDR_FORMAT
86              struct fi_info::addr_format field
87
88       FI_TYPE_TX_ATTR
89              struct fi_tx_attr
90
91       FI_TYPE_RX_ATTR
92              struct fi_rx_attr
93
94       FI_TYPE_EP_ATTR
95              struct fi_ep_attr
96
97       FI_TYPE_DOMAIN_ATTR
98              struct fi_domain_attr
99
100       FI_TYPE_FABRIC_ATTR
101              struct fi_fabric_attr
102
103       FI_TYPE_THREADING
104              enum fi_threading
105
106       FI_TYPE_PROGRESS
107              enum fi_progress
108
109       FI_TYPE_PROTOCOL
110              struct fi_ep_attr::protocol field
111
112       FI_TYPE_MSG_ORDER
113              struct fi_ep_attr::msg_order field
114
115       FI_TYPE_MODE
116              struct fi_info::mode field
117
118       FI_TYPE_AV_TYPE
119              enum fi_av_type
120
121       FI_TYPE_ATOMIC_TYPE
122              enum fi_datatype
123
124       FI_TYPE_ATOMIC_OP
125              enum fi_op
126
127       FI_TYPE_VERSION
128              Returns the library version of libfabric in  string  form.   The
129              data parameter is ignored.
130
131       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
135       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
139       FI_TYPE_MR_MODE
140              struct fi_domain_attr::mr_mode flags
141
142       FI_TYPE_OP_TYPE
143              enum fi_op_type
144
145       FI_TYPE_FID
146              struct fid *
147
148       FI_TYPE_HMEM_IFACE
149              enum fi_hmem_iface *
150
151       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
155       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

NOTES

160       The  following resources are associated with fabric domains: access do‐
161       mains, passive endpoints, and CM event queues.
162

FABRIC ATTRIBUTES

164       The fi_fabric_attr structure defines the set of  attributes  associated
165       with a fabric and a fabric provider.
166
167              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
175   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
182       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
186   name
187       A fabric identifier.
188
189   prov_name - Provider Name
190       The name of the underlying fabric provider.
191
192       To  request  an utility provider layered over a specific core provider,
193       both the provider names have to be specified using ";" as delimiter.
194
195       e.g.  "ofi_rxm;verbs" or "verbs;ofi_rxm"
196
197       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
208   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
213       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
216   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

RETURN VALUE

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

ERRORS

SEE ALSO

227       fabric(7), fi_getinfo(3), fi_domain(3), fi_eq(3), fi_endpoint(3)
228

AUTHORS

230       OpenFabrics.
231
232
233
234Libfabric Programmer's Manual     2020-10-20                      fi_fabric(3)
Impressum