core: Require using libfabric APIs to allocate fi_info structures

Disallow users hand-crafting or hand-copying their own fi_info structs.
This allows the library to allocate hidden fields for internal use.
Plus, there's no need to apps to do this, given that the API call is
way easier to use.

Signed-off-by: Sean Hefty <[email protected]>

man/fi_domain.3.md

@@ -41,6 +41,8 @@ int fi_set_ops(struct fid *domain, const char *name, uint64_t flags,
 
 *info*
 : Fabric information, including domain capabilities and attributes.
+  The struct fi_info must have been obtained using either fi_getinfo()
+  or fi_dupinfo().
 
 *domain*
 : An opened access domain.

man/fi_endpoint.3.md

@@ -124,8 +124,9 @@ DEPRECATED ssize_t fi_tx_size_left(struct fid_ep *ep);
   associated resource.
 
 *info*
-: Details about the fabric interface endpoint to be opened, obtained
-  from fi_getinfo.
+: Details about the fabric interface endpoint to be opened.
+  The struct fi_info must have been obtained using either fi_getinfo()
+  or fi_dupinfo().
 
 *ep*
 : A fabric endpoint.

man/fi_getinfo.3.md

@@ -42,7 +42,8 @@ struct fi_info *fi_dupinfo(const struct fi_info *info);
 
 *hints*
 : Reference to an fi_info structure that specifies criteria for
-  selecting the returned fabric information.
+  selecting the returned fabric information.  The fi_info hints
+  structure must be allocated using either fi_allocinfo() or fi_dupinfo().
 
 *info*
 : A pointer to a linked list of fi_info structures containing response
@@ -688,6 +689,12 @@ via fi_freeinfo().
 
 # NOTES
 
+Various libfabric calls, including fi_getinfo, take a struct fi_info as
+input.  Applications must use libfabric allocated fi_info structures.
+A zeroed struct fi_info can be allocated using fi_allocinfo, which may
+then be initialized by the user.  A struct fi_info may be copied for
+modification using the fi_dupinfo() call.
+
 If hints are provided, the operation will be controlled by the values
 that are supplied in the various fields (see section on _fi_info_).
 Applications that require specific communication interfaces, domains,