1fi_getinfo(3) Libfabric v1.6.1 fi_getinfo(3)
2
6 fi_getinfo, fi_freeinfo - Obtain / free fabric interface information
7 fi_allocinfo, fi_dupinfo - Allocate / duplicate an fi_info structure
9
11 #include <rdma/fabric.h>
12 int fi_getinfo(int version, const char *node, const char *service,
14 uint64_t flags, const struct fi_info *hints, struct fi_info **info);
15 void fi_freeinfo(struct fi_info *info);
17 struct fi_info *fi_allocinfo(void);
19 struct fi_info *fi_dupinfo(const struct fi_info *info);
21
23 version : Interface version requested by application.
24 node : Optional, name or fabric address to resolve.
26 service : Optional, service name or port number of address.
28 flags : Operation flags for the fi_getinfo call.
30 hints : Reference to an fi_info structure that specifies criteria for
32 selecting the returned fabric information.
33 info : A pointer to a linked list of fi_info structures containing
35 response information.
36
38 fi_getinfo returns information about available fabric services for
39 reaching specified node or service, subject to any provided hints.
40 Callers may specify NULL for node, service, and hints in order to
41 retrieve information about what providers are available and their opti‐
42 mal usage models. If no matching fabric information is available, info
43 will be set to NULL and the call will return -FI_ENODATA.
44 Based on the input hints, node, and service parameters, a list of fab‐
46 ric domains and endpoints will be returned. Each fi_info structure
47 will describe an endpoint that meets the application's specified commu‐
48 nication criteria. Each endpoint will be associated with a domain.
49 Applications can restrict the number of returned endpoints by including
50 additional criteria in their search hints. Relaxing or eliminating
51 input hints will increase the number and type of endpoints that are
52 available. Providers that return multiple endpoints to a single
53 fi_getinfo call should return the endpoints that are highest performing
54 first. Providers may indicate that an endpoint and domain can support
55 additional capabilities than those requested by the user only if such
56 support will not adversely affect application performance or security.
57 The version parameter is used by the application to request the desired
59 version of the interfaces. The version determines the format of all
60 data structures used by any of the fabric interfaces. Applications
61 should use the FI_VERSION(major, minor) macro to indicate the version,
62 with hard-coded integer values for the major and minor values. The
63 FI_MAJOR_VERSION and FI_MINOR_VERSION enum values defined in fabric.h
64 specify the latest version of the installed library. However, it is
65 recommended that the integer values for FI_MAJOR_VERSION and
66 FI_MINOR_VERSION be used, rather than referencing the enum types in
67 order to ensure compatibility with future versions of the library.
68 This protects against the application being built from source against a
69 newer version of the library that introduces new fields to data struc‐
70 tures, which would not be initialized by the application.
71 Node, service, or hints may be provided, with any combination being
73 supported. If node is provided, fi_getinfo will attempt to resolve the
74 fabric address to the given node. If node is not given, fi_getinfo
75 will attempt to resolve the fabric addressing information based on the
76 provided hints. Node is commonly used to provide a network address
77 (such as an IP address) or hostname. Service is usually associated
78 with a transport address (such as a TCP port number). Node and service
79 parameters may be mapped by providers to native fabric addresses.
80 Applications may also pass in an FI_ADDR_STR formatted address (see
81 format details below) as the node parameter. In such cases, the ser‐
82 vice parameter must be NULL.
83 The hints parameter, if provided, may be used to limit the resulting
85 output as indicated below. As a general rule, specifying a non-zero
86 value for input hints indicates that a provider must support the
87 requested value or fail the operation with -FI_ENODATA. With the
88 exception of mode bits, hints that are set to zero are treated as a
89 wildcard. A zeroed hint value results in providers either returning a
90 default value or a value that works best for their implementation.
91 Mode bits that are set to zero indicate the application does not sup‐
92 port any modes.
93 The caller must call fi_freeinfo to release fi_info structures returned
95 by this call.
96 The fi_allocinfo call will allocate and zero an fi_info structure and
98 all related substructures. The fi_dupinfo will duplicate a single
99 fi_info structure and all the substructures within it.
100
102 struct fi_info {
103 struct fi_info *next;
104 uint64_t caps;
105 uint64_t mode;
106 uint32_t addr_format;
107 size_t src_addrlen;
108 size_t dest_addrlen;
109 void *src_addr;
110 void *dest_addr;
111 fid_t handle;
112 struct fi_tx_attr *tx_attr;
113 struct fi_rx_attr *rx_attr;
114 struct fi_ep_attr *ep_attr;
115 struct fi_domain_attr *domain_attr;
116 struct fi_fabric_attr *fabric_attr;
117 };
118 next : Pointer to the next fi_info structure in the list. Will be NULL
120 if no more structures exist.
121 caps - fabric interface capabilities : If specified, indicates the
123 desired capabilities of the fabric interfaces. Supported capabilities
124 are listed in the Capabilities section below.
125 mode : Operational modes supported by the application. See the Mode
127 section below.
128 addr_format - address format : If specified, indicates the format of
130 addresses referenced by the fabric interfaces and data structures.
131 Supported formats are listed in the Addressing formats section below.
132 src_addrlen - source address length : Indicates the length of the
134 source address. This value must be > 0 if src_addr is non-NULL. This
135 field will be ignored in hints if FI_SOURCE flag is set, or src_addr is
136 NULL.
137 dest_addrlen - destination address length : Indicates the length of the
139 destination address. This value must be > 0 if dest_addr is non-NULL.
140 This field will be ignored in hints unless the node and service parame‐
141 ters are NULL or FI_SOURCE flag is set, or if dst_addr is NULL.
142 src_addr - source address : If specified, indicates the source address.
144 This field will be ignored in hints if FI_SOURCE flag is set. On out‐
145 put a provider shall return an address that corresponds to the indi‐
146 cated fabric, domain, node, and/or service fields. The format of the
147 address is indicated by the returned addr_format field. Note that any
148 returned address is only used when opening a local endpoint. The
149 address is not guaranteed to be usable by a peer process.
150 dest_addr - destination address : If specified, indicates the destina‐
152 tion address. This field will be ignored in hints unless the node and
153 service parameters are NULL or FI_SOURCE flag is set. If FI_SOURCE is
154 not specified, on output a provider shall return an address the corre‐
155 sponds to the indicated node and/or service fields, relative to the
156 fabric and domain. Note that any returned address is only usable
157 locally.
158 handle - provider context handle : References a provider specific han‐
160 dle. The use of this field is operation specific. Unless its use is
161 described for a given operation, the handle field must be NULL. It is
162 commonly used by applications that make use of connection-oriented end‐
163 points. For other applications, the field should usually be NULL.
164 This field is used when processing connection requests and responses.
166 It is also used to inherit endpoint's attributes. See fi_eq(3),
167 fi_reject(3), and fi_endpoint(3) .
168 tx_attr - transmit context attributes : Optionally supplied transmit
170 context attributes. Transmit context attributes may be specified and
171 returned as part of fi_getinfo. When provided as hints, requested val‐
172 ues of struct fi_tx_ctx_attr should be set. On output, the actual
173 transmit context attributes that can be provided will be returned.
174 Output values will be greater than or equal to the requested input val‐
175 ues.
176 rx_attr - receive context attributes : Optionally supplied receive con‐
178 text attributes. Receive context attributes may be specified and
179 returned as part of fi_getinfo. When provided as hints, requested val‐
180 ues of struct fi_rx_ctx_attr should be set. On output, the actual
181 receive context attributes that can be provided will be returned. Out‐
182 put values will be greater than or or equal to the requested input val‐
183 ues.
184 ep_attr - endpoint attributes : Optionally supplied endpoint
186 attributes. Endpoint attributes may be specified and returned as part
187 of fi_getinfo. When provided as hints, requested values of struct
188 fi_ep_attr should be set. On output, the actual endpoint attributes
189 that can be provided will be returned. Output values will be greater
190 than or equal to requested input values. See fi_endpoint(3) for
191 details.
192 domain_attr - domain attributes : Optionally supplied domain
194 attributes. Domain attributes may be specified and returned as part of
195 fi_getinfo. When provided as hints, requested values of struct
196 fi_domain_attr should be set. On output, the actual domain attributes
197 that can be provided will be returned. Output values will be greater
198 than or equal to requested input values. See fi_domain(3) for details.
199 fabric_attr - fabric attributes : Optionally supplied fabric
201 attributes. Fabric attributes may be specified and returned as part of
202 fi_getinfo. When provided as hints, requested values of struct fi_fab‐
203 ric_attr should be set. On output, the actual fabric attributes that
204 can be provided will be returned. See fi_fabric(3) for details.
205
207 Interface capabilities are obtained by OR-ing the following flags
208 together. If capabilities in the hint parameter are set to 0, the
209 underlying provider will return the set of capabilities which are sup‐
210 ported. Otherwise, providers will return data matching the specified
211 set of capabilities. Providers may indicate support for additional
212 capabilities beyond those requested when the use of expanded capabili‐
213 ties will not adversely affect performance or expose the application to
214 communication beyond that which was requested. Applications may use
215 this feature to request a minimal set of requirements, then check the
216 returned capabilities to enable additional optimizations.
217 FI_MSG : Specifies that an endpoint should support sending and receiv‐
219 ing messages or datagrams. Message capabilities imply support for send
220 and/or receive queues. Endpoints supporting this capability support
221 operations defined by struct fi_ops_msg.
222 The caps may be used to specify or restrict the type of messaging oper‐
224 ations that are supported. In the absence of any relevant flags,
225 FI_MSG implies the ability to send and receive messages. Applications
226 can use the FI_SEND and FI_RECV flags to optimize an endpoint as
227 send-only or receive-only.
228 FI_RMA : Specifies that the endpoint should support RMA read and write
230 operations. Endpoints supporting this capability support operations
231 defined by struct fi_ops_rma. In the absence of any relevant flags,
232 FI_RMA implies the ability to initiate and be the target of remote mem‐
233 ory reads and writes. Applications can use the FI_READ, FI_WRITE,
234 FI_REMOTE_READ, and FI_REMOTE_WRITE flags to restrict the types of RMA
235 operations supported by an endpoint.
236 FI_TAGGED : Specifies that the endpoint should handle tagged message
238 transfers. Tagged message transfers associate a user-specified key or
239 tag with each message that is used for matching purposes at the remote
240 side. Endpoints supporting this capability support operations defined
241 by struct fi_ops_tagged. In the absence of any relevant flags,
242 FI_TAGGED implies the ability to send and receive tagged messages.
243 Applications can use the FI_SEND and FI_RECV flags to optimize an end‐
244 point as send-only or receive-only.
245 FI_ATOMIC : Specifies that the endpoint supports some set of atomic
247 operations. Endpoints supporting this capability support operations
248 defined by struct fi_ops_atomic. In the absence of any relevant flags,
249 FI_ATOMIC implies the ability to initiate and be the target of remote
250 atomic reads and writes. Applications can use the FI_READ, FI_WRITE,
251 FI_REMOTE_READ, and FI_REMOTE_WRITE flags to restrict the types of
252 atomic operations supported by an endpoint.
253 FI_MULTICAST : Indicates that the endpoint support multicast data
255 transfers. This capability must be paired with at least one other data
256 transfer capability, (e.g. FI_MSG, FI_SEND, FI_RECV, ...).
257 FI_NAMED_RX_CTX : Requests that endpoints which support multiple
259 receive contexts allow an initiator to target (or name) a specific
260 receive context as part of a data transfer operation.
261 FI_DIRECTED_RECV : Requests that the communication endpoint use the
263 source address of an incoming message when matching it with a receive
264 buffer. If this capability is not set, then the src_addr parameter for
265 msg and tagged receive operations is ignored.
266 FI_MULTI_RECV : Specifies that the endpoint must support the
268 FI_MULTI_RECV flag when posting receive buffers.
269 FI_SOURCE : Requests that the endpoint return source addressing data as
271 part of its completion data. This capability only applies to connec‐
272 tionless endpoints. Note that returning source address information may
273 require that the provider perform address translation and/or look-up
274 based on data available in the underlying protocol in order to provide
275 the requested data, which may adversely affect performance. The per‐
276 formance impact may be greater for address vectors of type FI_AV_TABLE.
277 FI_READ : Indicates that the user requires an endpoint capable of ini‐
279 tiating reads against remote memory regions. This flag requires that
280 FI_RMA and/or FI_ATOMIC be set.
281 FI_WRITE : Indicates that the user requires an endpoint capable of ini‐
283 tiating writes against remote memory regions. This flag requires that
284 FI_RMA and/or FI_ATOMIC be set.
285 FI_SEND : Indicates that the user requires an endpoint capable of send‐
287 ing message data transfers. Message transfers include base message
288 operations as well as tagged message functionality.
289 FI_RECV : Indicates that the user requires an endpoint capable of
291 receiving message data transfers. Message transfers include base mes‐
292 sage operations as well as tagged message functionality.
293 FI_REMOTE_READ : Indicates that the user requires an endpoint capable
295 of receiving read memory operations from remote endpoints. This flag
296 requires that FI_RMA and/or FI_ATOMIC be set.
297 FI_REMOTE_WRITE : Indicates that the user requires an endpoint capable
299 of receiving write memory operations from remote endpoints. This flag
300 requires that FI_RMA and/or FI_ATOMIC be set.
301 FI_RMA_EVENT : Requests that an endpoint support the generation of com‐
303 pletion events when it is the target of an RMA and/or atomic operation.
304 This flag requires that FI_REMOTE_READ and/or FI_REMOTE_WRITE be
305 enabled on the endpoint.
306 FI_SHARED_AV : Requests or indicates support for address vectors which
308 may be shared among multiple processes.
309 FI_TRIGGER : Indicates that the endpoint should support triggered oper‐
311 ations. Endpoints support this capability must meet the usage model as
312 described by fi_trigger.3.
313 FI_FENCE : Indicates that the endpoint support the FI_FENCE flag on
315 data transfer operations. Support requires tracking that all previous
316 transmit requests to a specified remote endpoint complete prior to ini‐
317 tiating the fenced operation. Fenced operations are often used to
318 enforce ordering between operations that are not otherwise guaranteed
319 by the underlying provider or protocol.
320 FI_LOCAL_COMM : Indicates that the endpoint support host local communi‐
322 cation. This flag may be used in conjunction with FI_REMOTE_COMM to
323 indicate that local and remote communication are required. If neither
324 FI_LOCAL_COMM or FI_REMOTE_COMM are specified, then the provider will
325 indicate support for the configuration that minimally affects perfor‐
326 mance. Providers that set FI_LOCAL_COMM but not FI_REMOTE_COMM, for
327 example a shared memory provider, may only be used to communication
328 between processes on the same system.
329 FI_REMOTE_COMM : Indicates that the endpoint support communication with
331 endpoints located at remote nodes (across the fabric). See
332 FI_LOCAL_COMM for additional details. Providers that set
333 FI_REMOTE_COMM but not FI_LOCAL_COMM, for example NICs that lack loop‐
334 back support, cannot be used to communicate with processes on the same
335 system.
336 FI_SOURCE_ERR : Must be paired with FI_SOURCE. When specified, this
338 requests that raw source addressing data be returned as part of comple‐
339 tion data for any address that has not been inserted into the local
340 address vector. Use of this capability may require the provider to
341 validate incoming source address data against addresses stored in the
342 local address vector, which may adversely affect performance.
343 FI_RMA_PMEM : Indicates that the provider is 'persistent memory aware'
345 and supports RMA operations to and from persistent memory. Persistent
346 memory aware providers must support registration of memory that is
347 backed by non- volatile memory, RMA transfers to/from persistent mem‐
348 ory, and enhanced completion semantics. This flag requires that FI_RMA
349 be set. This capability is experimental.
350 Capabilities may be grouped into two general categories: primary and
352 secondary. Primary capabilities must explicitly be requested by an
353 application, and a provider must enable support for only those primary
354 capabilities which were selected. Secondary capabilities may option‐
355 ally be requested by an application. If requested, a provider must
356 support the capability or fail the fi_getinfo request (FI_ENODATA). A
357 provider may optionally report non-selected secondary capabilities if
358 doing so would not compromise performance or security.
359 Primary capabilities: FI_MSG, FI_RMA, FI_TAGGED, FI_ATOMIC, FI_MULTI‐
361 CAST, FI_NAMED_RX_CTX, FI_DIRECTED_RECV, FI_READ, FI_WRITE, FI_RECV,
362 FI_SEND, FI_REMOTE_READ, and FI_REMOTE_WRITE.
363 Secondary capabilities: FI_MULTI_RECV, FI_SOURCE, FI_RMA_EVENT,
365 FI_SHARED_AV, FI_TRIGGER, FI_FENCE, FI_LOCAL_COMM, FI_REMOTE_COMM,
366 FI_SOURCE_ERR, FI_RMA_PMEM.
367
369 The operational mode bits are used to convey requirements that an
370 application must adhere to when using the fabric interfaces. Modes
371 specify optimal ways of accessing the reported endpoint or domain.
372 Applications that are designed to support a specific mode of operation
373 may see improved performance when that mode is desired by the provider.
374 It is recommended that providers support applications that disable any
375 provider preferred modes.
376 On input to fi_getinfo, applications set the mode bits that they sup‐
378 port. On output, providers will clear mode bits that are not necessary
379 to achieve high-performance. Mode bits that remain set indicate appli‐
380 cation requirements for using the fabric interfaces created using the
381 returned fi_info. The set of modes are listed below. If a NULL hints
382 structure is provided, then the provider's supported set of modes will
383 be returned in the info structure(s).
384 FI_CONTEXT : Specifies that the provider requires that applications use
386 struct fi_context as their per operation context parameter for opera‐
387 tions that generated full completions. This structure should be
388 treated as opaque to the application. For performance reasons, this
389 structure must be allocated by the user, but may be used by the fabric
390 provider to track the operation. Typically, users embed struct fi_con‐
391 text within their own context structure. The struct fi_context must
392 remain valid until the corresponding operation completes or is success‐
393 fully canceled. As such, fi_context should NOT be allocated on the
394 stack. Doing so is likely to result in stack corruption that will be
395 difficult to debug. Users should not update or interpret the fields in
396 this structure, or reuse it until the original operation has completed.
397 If an operation does not generate a completion (i.e. the endpoint was
398 configured with FI_SELECTIVE_COMPLETION and the operation was not ini‐
399 tiated with the FI_COMPLETION flag) then the context parameter is
400 ignored by the fabric provider.The structure is specified in rdma/fab‐
401 ric.h.
402 FI_CONTEXT2 : This bit is similar to FI_CONTEXT, but doubles the
404 provider's requirement on the size of the per context structure. When
405 set, this specifies that the provider requires that applications use
406 struct fi_context2 as their per operation context parameter. Or,
407 optionally, an application can provide an array of two fi_context
408 structures (e.g. struct fi_context[2]) instead. The requirements for
409 using struct fi_context2 are identical as defined for FI_CONTEXT above.
410 FI_LOCAL_MR : The provider is optimized around having applications reg‐
412 ister memory for locally accessed data buffers. Data buffers used in
413 send and receive operations and as the source buffer for RMA and atomic
414 operations must be registered by the application for access domains
415 opened with this capability. This flag is defined for compatibility
416 and is ignored if the application version is 1.5 or later and the
417 domain mr_mode is set to anything other than FI_MR_BASIC or FI_MR_SCAL‐
418 ABLE. See the domain attribute mr_mode fi_domain(3) and fi_mr(3).
419 FI_MSG_PREFIX : Message prefix mode indicates that an application will
421 provide buffer space in front of all message send and receive buffers
422 for use by the provider. Typically, the provider uses this space to
423 implement a protocol, with the protocol headers being written into the
424 prefix area. The contents of the prefix space should be treated as
425 opaque. The use of FI_MSG_PREFIX may improve application performance
426 over certain providers by reducing the number of IO vectors referenced
427 by underlying hardware and eliminating provider buffer allocation.
428 FI_MSG_PREFIX only applies to send and receive operations, including
430 tagged sends and receives. RMA and atomics do not require the applica‐
431 tion to provide prefix buffers. Prefix buffer space must be provided
432 with all sends and receives, regardless of the size of the transfer or
433 other transfer options. The ownership of prefix buffers is treated the
434 same as the corresponding message buffers, but the size of the prefix
435 buffer is not counted toward any message limits, including inject.
436 Applications that support prefix mode must supply buffer space before
438 their own message data. The size of space that must be provided is
439 specified by the msg_prefix_size endpoint attribute. Providers are
440 required to define a msg_prefix_size that is a multiple of 8 bytes.
441 Additionally, applications may receive provider generated packets that
442 do not contain application data. Such received messages will indicate
443 a transfer size of that is equal to or smaller than msg_prefix_size.
444 The buffer pointer given to all send and receive operations must point
446 to the start of the prefix region of the buffer (as opposed to the pay‐
447 load). For scatter-gather send/recv operations, the prefix buffer must
448 be a contiguous region, though it may or may not be directly adjacent
449 to the payload portion of the buffer.
450 FI_ASYNC_IOV : Applications can reference multiple data buffers as part
452 of a single operation through the use of IO vectors (SGEs). Typically,
453 the contents of an IO vector are copied by the provider into an inter‐
454 nal buffer area, or directly to the underlying hardware. However, when
455 a large number of IOV entries are supported, IOV buffering may have a
456 negative impact on performance and memory consumption. The
457 FI_ASYNC_IOV mode indicates that the application must provide the
458 buffering needed for the IO vectors. When set, an application must not
459 modify an IO vector of length > 1, including any related memory
460 descriptor array, until the associated operation has completed.
461 FI_RX_CQ_DATA : This mode bit only applies to data transfers that set
463 FI_REMOTE_CQ_DATA. When set, a data transfer that carries remote CQ
464 data will consume a receive buffer at the target. This is true even
465 for operations that would normally not consume posted receive buffers,
466 such as RMA write operations.
467 FI_NOTIFY_FLAGS_ONLY : This bit indicates that general completion flags
469 may not be set by the provider, and are not needed by the application.
470 If specified, completion flags which simply report the type of opera‐
471 tion that completed (e.g. send or receive) may not be set. However,
472 completion flags that are used for remote notifications will still be
473 set when applicable. See fi_cq(3) for details on which completion
474 flags are valid when this mode bit is enabled.
475 FI_RESTRICTED_COMP : This bit indicates that the application will only
477 share completion queues and counters among endpoints, transmit con‐
478 texts, and receive contexts that have the same set of capability flags.
479
481 Multiple fabric interfaces take as input either a source or destination
482 address parameter. This includes struct fi_info (src_addr and
483 dest_addr), CM calls (getname, getpeer, connect, join, and leave), and
484 AV calls (insert, lookup, and straddr). The fi_info addr_format field
485 indicates the expected address format for these operations.
486 A provider may support one or more of the following addressing formats.
488 In some cases, a selected addressing format may need to be translated
489 or mapped into an address which is native to the fabric. See fi_av(3).
490 FI_FORMAT_UNSPEC : FI_FORMAT_UNSPEC indicates that a provider specific
492 address format should be selected. Provider specific addresses may be
493 protocol specific or a vendor proprietary format. Applications that
494 select FI_FORMAT_UNSPEC should be prepared to treat returned addressing
495 data as opaque. FI_FORMAT_UNSPEC targets apps which make use of an out
496 of band address exchange. Applications which use FI_FORMAT_UNSPEC may
497 use fi_getname() to obtain a provider specific address assigned to an
498 allocated endpoint.
499 FI_SOCKADDR : Address is of type sockaddr. The specific socket address
501 format will be determined at run time by interfaces examining the
502 sa_family field.
503 FI_SOCKADDR_IN : Address is of type sockaddr_in (IPv4).
505 FI_SOCKADDR_IN6 : Address is of type sockaddr_in6 (IPv6).
507 FI_SOCKADDR_IB : Address is of type sockaddr_ib (defined in Linux ker‐
509 nel source)
510 FI_ADDR_PSMX : Address is an Intel proprietary format that is used with
512 their PSMX (extended performance scaled messaging) protocol.
513 FI_ADDR_GNI : Address is a Cray proprietary format that is used with
515 their GNI protocol.
516 FI_ADDR_STR : Address is a formatted character string. The length and
518 content of the string is address and/or provider specific, but in gen‐
519 eral follows a URI model:
520 address_format[://[node][:[service][/[field3]...][?[key=value][&k2=v2]...]]]
522 Examples: - fi_sockaddr://10.31.6.12:7471 - fi_sock‐
524 addr_in6://[fe80::6:12]:7471 - fi_sockaddr://10.31.6.12:7471?qos=3
525 Since the string formatted address does not contain any provider infor‐
527 mation, the prov_name field of the fabric attribute structure should be
528 used to filter by provider if necessary.
529
531 The operation of the fi_getinfo call may be controlled through the use
532 of input flags. Valid flags include the following.
533 FI_NUMERICHOST : Indicates that the node parameter is a numeric string
535 representation of a fabric address, such as a dotted decimal IP
536 address. Use of this flag will suppress any lengthy name resolution
537 protocol.
538 FI_SOURCE : Indicates that the node and service parameters specify the
540 local source address to associate with an endpoint. If specified,
541 either the node and/or service parameter must be non-NULL. This flag
542 is often used with passive endpoints.
543 FI_PROV_ATTR_ONLY : Indicates that the caller is only querying for what
545 providers are potentially available. All providers will return exactly
546 one fi_info struct, regardless of whether that provider is usable on
547 the current platform or not. The returned fi_info struct will contain
548 default values for all members, with the exception of fabric_attr. The
549 fabric_attr member will have the prov_name and prov_version values
550 filled in.
551
553 fi_getinfo() returns 0 on success. On error, fi_getinfo() returns a
554 negative value corresponding to fabric errno. Fabric errno values are
555 defined in rdma/fi_errno.h.
556 fi_allocinfo() returns a pointer to a new fi_info structure on success,
558 or NULL on error. fi_dupinfo() duplicates a single fi_info structure
559 and all the substructures within it, returning a pointer to the new
560 fi_info structure on success, or NULL on error. Both calls require
561 that the returned fi_info structure be freed via fi_freeinfo().
562
564 FI_EBADFLAGS : The specified endpoint or domain capability or operation
565 flags are invalid.
566 FI_ENOMEM : Indicates that there was insufficient memory to complete
568 the operation.
569 FI_ENODATA : Indicates that no providers could be found which support
571 the requested fabric information.
572
574 If hints are provided, the operation will be controlled by the values
575 that are supplied in the various fields (see section on fiinfo_).
576 Applications that require specific communication interfaces, domains,
577 capabilities or other requirements, can specify them using fields in
578 hints. Libfabric returns a linked list in info that points to a list
579 of matching interfaces. info is set to NULL if there are no communica‐
580 tion interfaces or none match the input hints.
581 If node is provided, fi_getinfo will attempt to resolve the fabric
583 address to the given node. If node is not provided, fi_getinfo will
584 attempt to resolve the fabric addressing information based on the pro‐
585 vided hints. The caller must call fi_freeinfo to release fi_info
586 structures returned by fi_getinfo.
587 If neither node, service or hints are provided, then fi_getinfo simply
589 returns the list all available communication interfaces.
590 Multiple threads may call fi_getinfo simultaneously, without any
592 requirement for serialization.
593
595 fi_open(3), fi_endpoint(3), fi_domain(3)
596
598 OpenFabrics.
599Libfabric Programmer's Manual 2018-02-13 fi_getinfo(3)