1fi_domain(3) Libfabric v1.10.0 fi_domain(3)
2
3
4
6 fi_domain - Open a fabric access domain
7
9 #include <rdma/fabric.h>
10
11 #include <rdma/fi_domain.h>
12
13 int fi_domain(struct fid_fabric *fabric, struct fi_info *info,
14 struct fid_domain **domain, void *context);
15
16 int fi_close(struct fid *domain);
17
18 int fi_domain_bind(struct fid_domain *domain, struct fid *eq,
19 uint64_t flags);
20
21 int fi_open_ops(struct fid *domain, const char *name, uint64_t flags,
22 void **ops, void *context);
23
25 fabric Fabric domain
26
27 info Fabric information, including domain capabilities and at‐
28 tributes.
29
30 domain An opened access domain.
31
32 context
33 User specified context associated with the domain. This context
34 is returned as part of any asynchronous event associated with
35 the domain.
36
37 eq Event queue for asynchronous operations initiated on the domain.
38
39 name Name associated with an interface.
40
41 ops Fabric interface operations.
42
44 An access domain typically refers to a physical or virtual NIC or hard‐
45 ware port; however, a domain may span across multiple hardware compo‐
46 nents for fail-over or data striping purposes. A domain defines the
47 boundary for associating different resources together. Fabric re‐
48 sources belonging to the same domain may share resources.
49
50 fi_domain
51 Opens a fabric access domain, also referred to as a resource domain.
52 Fabric domains are identified by a name. The properties of the opened
53 domain are specified using the info parameter.
54
55 fi_open_ops
56 fi_open_ops is used to open provider specific interfaces. Provider in‐
57 terfaces may be used to access low-level resources and operations that
58 are specific to the opened resource domain. The details of domain in‐
59 terfaces are outside the scope of this documentation.
60
61 fi_domain_bind
62 Associates an event queue with the domain. An event queue bound to a
63 domain will be the default EQ associated with asynchronous control
64 events that occur on the domain or active endpoints allocated on a do‐
65 main. This includes CM events. Endpoints may direct their control
66 events to alternate EQs by binding directly with the EQ.
67
68 Binding an event queue to a domain with the FI_REG_MR flag indicates
69 that the provider should perform all memory registration operations
70 asynchronously, with the completion reported through the event queue.
71 If an event queue is not bound to the domain with the FI_REG_MR flag,
72 then memory registration requests complete synchronously.
73
74 See fi_av_bind(3), fi_ep_bind(3), fi_mr_bind(3), fi_pep_bind(3), and
75 fi_scalable_ep_bind(3) for more information.
76
77 fi_close
78 The fi_close call is used to release all resources associated with a
79 domain or interface. All objects associated with the opened domain
80 must be released prior to calling fi_close, otherwise the call will re‐
81 turn -FI_EBUSY.
82
84 The fi_domain_attr structure defines the set of attributes associated
85 with a domain.
86
87 struct fi_domain_attr {
88 struct fid_domain *domain;
89 char *name;
90 enum fi_threading threading;
91 enum fi_progress control_progress;
92 enum fi_progress data_progress;
93 enum fi_resource_mgmt resource_mgmt;
94 enum fi_av_type av_type;
95 int mr_mode;
96 size_t mr_key_size;
97 size_t cq_data_size;
98 size_t cq_cnt;
99 size_t ep_cnt;
100 size_t tx_ctx_cnt;
101 size_t rx_ctx_cnt;
102 size_t max_ep_tx_ctx;
103 size_t max_ep_rx_ctx;
104 size_t max_ep_stx_ctx;
105 size_t max_ep_srx_ctx;
106 size_t cntr_cnt;
107 size_t mr_iov_limit;
108 uint64_t caps;
109 uint64_t mode;
110 uint8_t *auth_key;
111 size_t auth_key_size;
112 size_t max_err_data;
113 size_t mr_cnt;
114 uint32_t tclass;
115 };
116
117 domain
118 On input to fi_getinfo, a user may set this to an opened domain in‐
119 stance to restrict output to the given domain. On output from fi_get‐
120 info, if no domain was specified, but the user has an opened instance
121 of the named domain, this will reference the first opened instance. If
122 no instance has been opened, this field will be NULL.
123
124 The domain instance returned by fi_getinfo should only be considered
125 valid if the application does not close any domain instances from an‐
126 other thread while fi_getinfo is being processed.
127
128 Name
129 The name of the access domain.
130
131 Multi-threading Support (threading)
132 The threading model specifies the level of serialization required of an
133 application when using the libfabric data transfer interfaces. Control
134 interfaces are always considered thread safe, and may be accessed by
135 multiple threads. Applications which can guarantee serialization in
136 their access of provider allocated resources and interfaces enables a
137 provider to eliminate lower-level locks.
138
139 FI_THREAD_COMPLETION
140 The completion threading model is intended for providers that
141 make use of manual progress. Applications must serialize access
142 to all objects that are associated through the use of having a
143 shared completion structure. This includes endpoint, transmit
144 context, receive context, completion queue, counter, wait set,
145 and poll set objects.
146
147 For example, threads must serialize access to an endpoint and its bound
148 completion queue(s) and/or counters. Access to endpoints that share
149 the same completion queue must also be serialized.
150
151 The use of FI_THREAD_COMPLETION can increase parallelism over
152 FI_THREAD_SAFE, but requires the use of isolated resources.
153
154 FI_THREAD_DOMAIN
155 A domain serialization model requires applications to serialize
156 access to all objects belonging to a domain.
157
158 FI_THREAD_ENDPOINT
159 The endpoint threading model is similar to FI_THREAD_FID, but
160 with the added restriction that serialization is required when
161 accessing the same endpoint, even if multiple transmit and re‐
162 ceive contexts are used. Conceptually, FI_THREAD_ENDPOINT maps
163 well to providers that implement fabric services in hardware but
164 use a single command queue to access different data flows.
165
166 FI_THREAD_FID
167 A fabric descriptor (FID) serialization model requires applica‐
168 tions to serialize access to individual fabric resources associ‐
169 ated with data transfer operations and completions. Multiple
170 threads must be serialized when accessing the same endpoint,
171 transmit context, receive context, completion queue, counter,
172 wait set, or poll set. Serialization is required only by
173 threads accessing the same object.
174
175 For example, one thread may be initiating a data transfer on an end‐
176 point, while another thread reads from a completion queue associated
177 with the endpoint.
178
179 Serialization to endpoint access is only required when accessing the
180 same endpoint data flow. Multiple threads may initiate transfers on
181 different transmit contexts of the same endpoint without serializing,
182 and no serialization is required between the submission of data trans‐
183 mit requests and data receive operations.
184
185 In general, FI_THREAD_FID allows the provider to be implemented without
186 needing internal locking when handling data transfers. Conceptually,
187 FI_THREAD_FID maps well to providers that implement fabric services in
188 hardware and provide separate command queues to different data flows.
189
190 FI_THREAD_SAFE
191 A thread safe serialization model allows a multi-threaded appli‐
192 cation to access any allocated resources through any interface
193 without restriction. All providers are required to support
194 FI_THREAD_SAFE.
195
196 FI_THREAD_UNSPEC
197 This value indicates that no threading model has been defined.
198 It may be used on input hints to the fi_getinfo call. When
199 specified, providers will return a threading model that allows
200 for the greatest level of parallelism.
201
202 Progress Models (control_progress / data_progress)
203 Progress is the ability of the underlying implementation to complete
204 processing of an asynchronous request. In many cases, the processing
205 of an asynchronous request requires the use of the host processor. For
206 example, a received message may need to be matched with the correct
207 buffer, or a timed out request may need to be retransmitted. For per‐
208 formance reasons, it may be undesirable for the provider to allocate a
209 thread for this purpose, which will compete with the application
210 threads.
211
212 Control progress indicates the method that the provider uses to make
213 progress on asynchronous control operations. Control operations are
214 functions which do not directly involve the transfer of application da‐
215 ta between endpoints. They include address vector, memory registra‐
216 tion, and connection management routines.
217
218 Data progress indicates the method that the provider uses to make
219 progress on data transfer operations. This includes message queue,
220 RMA, tagged messaging, and atomic operations, along with their comple‐
221 tion processing.
222
223 Progress frequently requires action being taken at both the transmit‐
224 ting and receiving sides of an operation. This is often a requirement
225 for reliable transfers, as a result of retry and acknowledgement pro‐
226 cessing.
227
228 To balance between performance and ease of use, two progress models are
229 defined.
230
231 FI_PROGRESS_AUTO
232 This progress model indicates that the provider will make for‐
233 ward progress on an asynchronous operation without further in‐
234 tervention by the application. When FI_PROGRESS_AUTO is provid‐
235 ed as output to fi_getinfo in the absence of any progress hints,
236 it often indicates that the desired functionality is implemented
237 by the provider hardware or is a standard service of the operat‐
238 ing system.
239
240 All providers are required to support FI_PROGRESS_AUTO. However, if a
241 provider does not natively support automatic progress, forcing the use
242 of FI_PROGRESS_AUTO may result in threads being allocated below the
243 fabric interfaces.
244
245 FI_PROGRESS_MANUAL
246 This progress model indicates that the provider requires the use
247 of an application thread to complete an asynchronous request.
248 When manual progress is set, the provider will attempt to ad‐
249 vance an asynchronous operation forward when the application at‐
250 tempts to wait on or read an event queue, completion queue, or
251 counter where the completed operation will be reported.
252 Progress also occurs when the application processes a poll or
253 wait set that has been associated with the event or completion
254 queue.
255
256 Only wait operations defined by the fabric interface will result in an
257 operation progressing. Operating system or external wait functions,
258 such as select, poll, or pthread routines, cannot.
259
260 Manual progress requirements not only apply to endpoints that initiate
261 transmit operations, but also to endpoints that may be the target of
262 such operations. This holds true even if the target endpoint will not
263 generate completion events for the operations. For example, an end‐
264 point that acts purely as the target of RMA or atomic operations that
265 uses manual progress may still need application assistance to process
266 received operations.
267
268 FI_PROGRESS_UNSPEC
269 This value indicates that no progress model has been defined.
270 It may be used on input hints to the fi_getinfo call.
271
272 Resource Management (resource_mgmt)
273 Resource management (RM) is provider and protocol support to protect
274 against overrunning local and remote resources. This includes local
275 and remote transmit contexts, receive contexts, completion queues, and
276 source and target data buffers.
277
278 When enabled, applications are given some level of protection against
279 overrunning provider queues and local and remote data buffers. Such
280 support may be built directly into the hardware and/or network proto‐
281 col, but may also require that checks be enabled in the provider soft‐
282 ware. By disabling resource management, an application assumes all re‐
283 sponsibility for preventing queue and buffer overruns, but doing so may
284 allow a provider to eliminate internal synchronization calls, such as
285 atomic variables or locks.
286
287 It should be noted that even if resource management is disabled, the
288 provider implementation and protocol may still provide some level of
289 protection against overruns. However, such protection is not guaran‐
290 teed. The following values for resource management are defined.
291
292 FI_RM_DISABLED
293 The provider is free to select an implementation and protocol
294 that does not protect against resource overruns. The applica‐
295 tion is responsible for resource protection.
296
297 FI_RM_ENABLED
298 Resource management is enabled for this provider domain.
299
300 FI_RM_UNSPEC
301 This value indicates that no resource management model has been
302 defined. It may be used on input hints to the fi_getinfo call.
303
304 The behavior of the various resource management options depends on
305 whether the endpoint is reliable or unreliable, as well as provider and
306 protocol specific implementation details, as shown in the following ta‐
307 ble. The table assumes that all peers enable or disable RM the same.
308
309 Resource DGRAM EP-no RM DGRAM EP-with RM RDM/MSG EP-no RDM/MSG EP-with
310 RM RM
311 ───────────────────────────────────────────────────────────────────────────────────
312 Tx Ctx undefined error EAGAIN undefined error EAGAIN
313 Rx Ctx undefined error EAGAIN undefined error EAGAIN
314 Tx CQ undefined error EAGAIN undefined error EAGAIN
315 Rx CQ undefined error EAGAIN undefined error EAGAIN
316 Target dropped dropped transmit error retried
317 EP
318 No Rx dropped dropped transmit error retried
319 Buffer
320 Rx Buf truncate or drop truncate or drop truncate or er‐ truncate or er‐
321 Overrun ror ror
322 Un‐ not applicable not applicable transmit error transmit error
323 matched
324 RMA
325 RMA not applicable not applicable transmit error transmit error
326 Overrun
327
328 The resource column indicates the resource being accessed by a data
329 transfer operation.
330
331 Tx Ctx / Rx Ctx
332 Refers to the transmit/receive contexts when a data transfer op‐
333 eration is submitted. When RM is enabled, attempting to submit
334 a request will fail if the context is full. If RM is disabled,
335 an undefined error (provider specific) will occur. Such errors
336 should be considered fatal to the context, and applications must
337 take steps to avoid queue overruns.
338
339 Tx CQ / Rx CQ
340 Refers to the completion queue associated with the Tx or Rx con‐
341 text when a local operation completes. When RM is disabled, ap‐
342 plications must take care to ensure that completion queues do
343 not get overrun. When an overrun occurs, an undefined, but fa‐
344 tal, error will occur affecting all endpoints associated with
345 the CQ. Overruns can be avoided by sizing the CQs appropriately
346 or by deferring the posting of a data transfer operation unless
347 CQ space is available to store its completion. When RM is en‐
348 abled, providers may use different mechanisms to prevent CQ
349 overruns. This includes failing (returning -FI_EAGAIN) the
350 posting of operations that could result in CQ overruns, or in‐
351 ternally retrying requests (which will be hidden from the appli‐
352 cation). See notes at the end of this section regarding CQ re‐
353 source management restrictions.
354
355 Target EP / No Rx Buffer
356 Target EP refers to resources associated with the endpoint that
357 is the target of a transmit operation. This includes the target
358 endpoint's receive queue, posted receive buffers (no Rx buf‐
359 fers), the receive side completion queue, and other related
360 packet processing queues. The defined behavior is that seen by
361 the initiator of a request. For FI_EP_DGRAM endpoints, if the
362 target EP queues are unable to accept incoming messages, re‐
363 ceived messages will be dropped. For reliable endpoints, if RM
364 is disabled, the transmit operation will complete in error. If
365 RM is enabled, the provider will internally retry the operation.
366
367 Rx Buffer Overrun
368 This refers to buffers posted to receive incoming tagged or un‐
369 tagged messages, with the behavior defined from the viewpoint of
370 the sender. The behavior for handling received messages that
371 are larger than the buffers provided by the application is
372 provider specific. Providers may either truncate the message
373 and report a successful completion, or fail the operation. For
374 datagram endpoints, failed sends will result in the message be‐
375 ing dropped. For reliable endpoints, send operations may com‐
376 plete successfully, yet be truncated at the receive side. This
377 can occur when the target side buffers received data until an
378 application buffer is made available. The completion status may
379 also be dependent upon the completion model selected byt the ap‐
380 plication (e.g. FI_DELIVERY_COMPLETE versus FI_TRANSMIT_COM‐
381 PLETE).
382
383 Unmatched RMA / RMA Overrun
384 Unmatched RMA and RMA overruns deal with the processing of RMA
385 and atomic operations. Unlike send operations, RMA operations
386 that attempt to access a memory address that is either not reg‐
387 istered for such operations, or attempt to access outside of the
388 target memory region will fail, resulting in a transmit error.
389
390 When a resource management error occurs on an endpoint, the endpoint is
391 transitioned into a disabled state. Any operations which have not al‐
392 ready completed will fail and be discarded. For unconnected endpoints,
393 the endpoint must be re-enabled before it will accept new data transfer
394 operations. For connected endpoints, the connection is torn down and
395 must be re-established.
396
397 There is one notable restriction on the protections offered by resource
398 management. This occurs when resource management is enabled on an end‐
399 point that has been bound to completion queue(s) using the FI_SELEC‐
400 TIVE_COMPLETION flag. Operations posted to such an endpoint may speci‐
401 fy that a successful completion should not generate a entry on the cor‐
402 responding completion queue. (I.e. the operation leaves the FI_COM‐
403 PLETION flag unset). In such situations, the provider is not required
404 to reserve an entry in the completion queue to handle the case where
405 the operation fails and does generate a CQ entry, which would effec‐
406 tively require tracking the operation to completion. Applications con‐
407 cerned with avoiding CQ overruns in the occurrence of errors must en‐
408 sure that there is sufficient space in the CQ to report failed opera‐
409 tions. This can typically be achieved by sizing the CQ to at least the
410 same size as the endpoint queue(s) that are bound to it.
411
412 AV Type (av_type)
413 Specifies the type of address vectors that are usable with this domain.
414 For additional details on AV type, see fi_av(3). The following values
415 may be specified.
416
417 FI_AV_MAP
418 Only address vectors of type AV map are requested or supported.
419
420 FI_AV_TABLE
421 Only address vectors of type AV index are requested or support‐
422 ed.
423
424 FI_AV_UNSPEC
425 Any address vector format is requested and supported.
426
427 Address vectors are only used by connectionless endpoints. Applica‐
428 tions that require the use of a specific type of address vector should
429 set the domain attribute av_type to the necessary value when calling
430 fi_getinfo. The value FI_AV_UNSPEC may be used to indicate that the
431 provider can support either address vector format. In this case, a
432 provider may return FI_AV_UNSPEC to indicate that either format is sup‐
433 portable, or may return another AV type to indicate the optimal AV type
434 supported by this domain.
435
436 Memory Registration Mode (mr_mode)
437 Defines memory registration specific mode bits used with this domain.
438 Full details on MR mode options are available in fi_mr(3). The follow‐
439 ing values may be specified.
440
441 FI_MR_ALLOCATED
442 Indicates that memory registration occurs on allocated data buf‐
443 fers, and physical pages must back all virtual addresses being
444 registered.
445
446 FI_MR_ENDPOINT
447 Memory registration occurs at the endpoint level, rather than
448 domain.
449
450 FI_MR_LOCAL
451 The provider is optimized around having applications register
452 memory for locally accessed data buffers. Data buffers used in
453 send and receive operations and as the source buffer for RMA and
454 atomic operations must be registered by the application for ac‐
455 cess domains opened with this capability.
456
457 FI_MR_MMU_NOTIFY
458 Indicates that the application is responsible for notifying the
459 provider when the page tables referencing a registered memory
460 region may have been updated.
461
462 FI_MR_PROV_KEY
463 Memory registration keys are selected and returned by the
464 provider.
465
466 FI_MR_RAW
467 The provider requires additional setup as part of their memory
468 registration process. This mode is required by providers that
469 use a memory key that is larger than 64-bits.
470
471 FI_MR_RMA_EVENT
472 Indicates that the memory regions associated with completion
473 counters must be explicitly enabled after being bound to any
474 counter.
475
476 FI_MR_UNSPEC
477 Defined for compatibility -- library versions 1.4 and earlier.
478 Setting mr_mode to 0 indicates that FI_MR_BASIC or FI_MR_SCAL‐
479 ABLE are requested and supported.
480
481 FI_MR_VIRT_ADDR
482 Registered memory regions are referenced by peers using the vir‐
483 tual address of the registered memory region, rather than a
484 0-based offset.
485
486 FI_MR_BASIC
487 Defined for compatibility -- library versions 1.4 and earlier.
488 Only basic memory registration operations are requested or sup‐
489 ported. This mode is equivalent to the FI_MR_VIRT_ADDR,
490 FI_MR_ALLOCATED, and FI_MR_PROV_KEY flags being set in later li‐
491 brary versions. This flag may not be used in conjunction with
492 other mr_mode bits.
493
494 FI_MR_SCALABLE
495 Defined for compatibility -- library versions 1.4 and earlier.
496 Only scalable memory registration operations are requested or
497 supported. Scalable registration uses offset based addressing,
498 with application selectable memory keys. For library versions
499 1.5 and later, this is the default if no mr_mode bits are set.
500 This flag may not be used in conjunction with other mr_mode
501 bits.
502
503 Buffers used in data transfer operations may require notifying the
504 provider of their use before a data transfer can occur. The mr_mode
505 field indicates the type of memory registration that is required, and
506 when registration is necessary. Applications that require the use of a
507 specific registration mode should set the domain attribute mr_mode to
508 the necessary value when calling fi_getinfo. The value FI_MR_UNSPEC
509 may be used to indicate support for any registration mode.
510
511 MR Key Size (mr_key_size)
512 Size of the memory region remote access key, in bytes. Applications
513 that request their own MR key must select a value within the range
514 specified by this value. Key sizes larger than 8 bytes require using
515 the FI_RAW_KEY mode bit.
516
517 CQ Data Size (cq_data_size)
518 Applications may include a small message with a data transfer that is
519 placed directly into a remote completion queue as part of a completion
520 event. This is referred to as remote CQ data (sometimes referred to as
521 immediate data). This field indicates the number of bytes that the
522 provider supports for remote CQ data. If supported (non-zero value is
523 returned), the minimum size of remote CQ data must be at least 4-bytes.
524
525 Completion Queue Count (cq_cnt)
526 The optimal number of completion queues supported by the domain, rela‐
527 tive to any specified or default CQ attributes. The cq_cnt value may
528 be a fixed value of the maximum number of CQs supported by the underly‐
529 ing hardware, or may be a dynamic value, based on the default at‐
530 tributes of an allocated CQ, such as the CQ size and data format.
531
532 Endpoint Count (ep_cnt)
533 The total number of endpoints supported by the domain, relative to any
534 specified or default endpoint attributes. The ep_cnt value may be a
535 fixed value of the maximum number of endpoints supported by the under‐
536 lying hardware, or may be a dynamic value, based on the default at‐
537 tributes of an allocated endpoint, such as the endpoint capabilities
538 and size. The endpoint count is the number of addressable endpoints
539 supported by the provider.
540
541 Transmit Context Count (tx_ctx_cnt)
542 The number of outbound command queues optimally supported by the
543 provider. For a low-level provider, this represents the number of com‐
544 mand queues to the hardware and/or the number of parallel transmit en‐
545 gines effectively supported by the hardware and caches. Applications
546 which allocate more transmit contexts than this value will end up shar‐
547 ing underlying resources. By default, there is a single transmit con‐
548 text associated with each endpoint, but in an advanced usage model, an
549 endpoint may be configured with multiple transmit contexts.
550
551 Receive Context Count (rx_ctx_cnt)
552 The number of inbound processing queues optimally supported by the
553 provider. For a low-level provider, this represents the number hard‐
554 ware queues that can be effectively utilized for processing incoming
555 packets. Applications which allocate more receive contexts than this
556 value will end up sharing underlying resources. By default, a single
557 receive context is associated with each endpoint, but in an advanced
558 usage model, an endpoint may be configured with multiple receive con‐
559 texts.
560
561 Maximum Endpoint Transmit Context (max_ep_tx_ctx)
562 The maximum number of transmit contexts that may be associated with an
563 endpoint.
564
565 Maximum Endpoint Receive Context (max_ep_rx_ctx)
566 The maximum number of receive contexts that may be associated with an
567 endpoint.
568
569 Maximum Sharing of Transmit Context (max_ep_stx_ctx)
570 The maximum number of endpoints that may be associated with a shared
571 transmit context.
572
573 Maximum Sharing of Receive Context (max_ep_srx_ctx)
574 The maximum number of endpoints that may be associated with a shared
575 receive context.
576
577 Counter Count (cntr_cnt)
578 The optimal number of completion counters supported by the domain. The
579 cq_cnt value may be a fixed value of the maximum number of counters
580 supported by the underlying hardware, or may be a dynamic value, based
581 on the default attributes of the domain.
582
583 MR IOV Limit (mr_iov_limit)
584 This is the maximum number of IO vectors (scatter-gather elements) that
585 a single memory registration operation may reference.
586
587 Capabilities (caps)
588 Domain level capabilities. Domain capabilities indicate domain level
589 features that are supported by the provider.
590
591 FI_LOCAL_COMM
592 At a conceptual level, this field indicates that the underlying
593 device supports loopback communication. More specifically, this
594 field indicates that an endpoint may communicate with other end‐
595 points that are allocated from the same underlying named domain.
596 If this field is not set, an application may need to use an al‐
597 ternate domain or mechanism (e.g. shared memory) to communicate
598 with peers that execute on the same node.
599
600 FI_REMOTE_COMM
601 This field indicates that the underlying provider supports com‐
602 munication with nodes that are reachable over the network. If
603 this field is not set, then the provider only supports communi‐
604 cation between processes that execute on the same node -- a
605 shared memory provider, for example.
606
607 FI_SHARED_AV
608 Indicates that the domain supports the ability to share address
609 vectors among multiple processes using the named address vector
610 feature.
611
612 See fi_getinfo(3) for a discussion on primary versus secondary capabil‐
613 ities. All domain capabilities are considered secondary capabilities.
614
615 mode
616 The operational mode bit related to using the domain.
617
618 FI_RESTRICTED_COMP
619 This bit indicates that the domain limits completion queues and
620 counters to only be used with endpoints, transmit contexts, and
621 receive contexts that have the same set of capability flags.
622
623 Default authorization key (auth_key)
624 The default authorization key to associate with endpoint and memory
625 registrations created within the domain. This field is ignored unless
626 the fabric is opened with API version 1.5 or greater.
627
628 Default authorization key length (auth_key_size)
629 The length in bytes of the default authorization key for the domain.
630 If set to 0, then no authorization key will be associated with end‐
631 points and memory registrations created within the domain unless speci‐
632 fied in the endpoint or memory registration attributes. This field is
633 ignored unless the fabric is opened with API version 1.5 or greater.
634
635 Max Error Data Size (max_err_data)
636 : The maximum amount of error data, in bytes, that may be returned as
637 part of a completion or event queue error. This value corresponds to
638 the err_data_size field in struct fi_cq_err_entry and struct
639 fi_eq_err_entry.
640
641 Memory Regions Count (mr_cnt)
642 The optimal number of memory regions supported by the domain, or end‐
643 point if the mr_mode FI_MR_ENDPOINT bit has been set. The mr_cnt value
644 may be a fixed value of the maximum number of MRs supported by the un‐
645 derlying hardware, or may be a dynamic value, based on the default at‐
646 tributes of the domain, such as the supported memory registration
647 modes. Applications can set the mr_cnt on input to fi_getinfo, in or‐
648 der to indicate their memory registration requirements. Doing so may
649 allow the provider to optimize any memory registration cache or lookup
650 tables.
651
652 Traffic Class (tclass)
653 This specifies the default traffic class that will be associated any
654 endpoints created within the domain. See [fi_endpoint(3)](fi_end‐
655 point.3.html for additional information.
656
658 Returns 0 on success. On error, a negative value corresponding to fab‐
659 ric errno is returned. Fabric errno values are defined in rdma/fi_er‐
660 rno.h.
661
663 Users should call fi_close to release all resources allocated to the
664 fabric domain.
665
666 The following fabric resources are associated with domains: active end‐
667 points, memory regions, completion event queues, and address vectors.
668
669 Domain attributes reflect the limitations and capabilities of the un‐
670 derlying hardware and/or software provider. They do not reflect system
671 limitations, such as the number of physical pages that an application
672 may pin or number of file descriptors that the application may open.
673 As a result, the reported maximums may not be achievable, even on a
674 lightly loaded systems, without an administrator configuring system re‐
675 sources appropriately for the installed provider(s).
676
678 fi_getinfo(3), fi_endpoint(3), fi_av(3), fi_ep(3), fi_eq(3), fi_mr(3)
679
681 OpenFabrics.
682
683
684
685Libfabric Programmer's Manual 2020-02-07 fi_domain(3)