fabric: Add version to fi_getinfo

Update fi_getinfo to accept a version number (major, minor). The version data is used to indicate what data structures an application and/or provider will use. Signed-off-by: Sean Hefty <[email protected]>
ofiwg · Sep 7, 2014 · 8434108 · 8434108
1 parent d0cc356
commit 8434108
Show file tree

Hide file tree

Showing 9 changed files with 52 additions and 29 deletions.
diff --git a/include/rdma/fabric.h b/include/rdma/fabric.h
@@ -56,6 +56,10 @@ enum {
 	FI_VERSION_MAX		= 64
 };
 
+#define FI_VERSION(major, minor) ((major << 16) | (minor))
+#define FI_MAJOR(version)	(version >> 16)
+#define FI_MINOR(version)	(version & 0xFFFF)
+
 /*
  * Vendor specific protocols/etc. are encoded as OUI, followed by vendor
  * specific data.
@@ -225,8 +229,8 @@ struct fid {
 
 #define FI_NUMERICHOST		(1ULL << 1)
 
-int fi_getinfo(const char *node, const char *service, uint64_t flags,
-	       struct fi_info *hints, struct fi_info **info);
+int fi_getinfo(int version, const char *node, const char *service,
+	       uint64_t flags, struct fi_info *hints, struct fi_info **info);
 void fi_freeinfo(struct fi_info *info);
 
 struct fi_attr {

diff --git a/include/rdma/fi_prov.h b/include/rdma/fi_prov.h
@@ -51,19 +51,19 @@ extern "C" {
 
 struct fi_ops_prov {
 	size_t	size;
-	int	(*getinfo)(const char *node, const char *service, uint64_t flags,
-			struct fi_info *hints, struct fi_info **info);
+	int	(*getinfo)(int version, const char *node, const char *service,
+			uint64_t flags, struct fi_info *hints, struct fi_info **info);
 	int	(*freeinfo)(struct fi_info *info);
 	int	(*domain)(struct fid_fabric *fabric, struct fi_info *info,
 			struct fid_domain **dom, void *context);
 	int	(*if_open)(const char *res_name, const char *if_name,
 			uint64_t flags, struct fid **fid, void *context);
 };
 
-int fi_version_register(int maj_ver, int min_ver, struct fi_ops_prov *ops);
+int fi_version_register(int version, struct fi_ops_prov *ops);
 static inline int fi_register(struct fi_ops_prov *ops)
 {
-	return fi_version_register(FI_MAJOR_VERSION, FI_MINOR_VERSION, ops);
+	return fi_version_register(FI_VERSION(FI_MAJOR_VERSION, FI_MINOR_VERSION), ops);
 }
 
 

diff --git a/man/fi_getinfo.3 b/man/fi_getinfo.3
@@ -4,11 +4,13 @@ fi_getinfo / fi_freeinfo \- Obtain / free fabric interface information
 .SH SYNOPSIS
 .B "#include <rdma/fabric.h>"
 .HP
-.BI "int fi_getinfo(const char *" node ", const char *" service ","
+.BI "int fi_getinfo(int " version ", const char *" node ", const char *" service ","
 .BI "uint64_t " flags ", struct fi_info *" hints ", struct fi_info **" info ");"
 .HP
 .BI "int fi_freeinfo(struct fi_info *" info ");"
 .SH ARGUMENTS
+.IP "version"
+Interface version requested by application.
 .IP "node"
 Optional, name or fabric address to resolve.
 .IP "service"
@@ -27,6 +29,19 @@ node or service, subject to any provided hints.  Callers must provide at least
 one of the node, service, or hints parameters.  If no matching fabric information
 is available, info will be set to NULL.
 .PP
+The version parameter is used by the application to request the desired
+version of the interfaces.  The version determines the format of all data
+structures used by any of the fabric interfaces.  Applications should use the
+FI_VERSION(major, minor) macro to indicate the version, with hard-coded integer
+values for the major and minor values.  The FI_MAJOR_VERSION and FI_MINOR_VERSION
+enum values defined in fabric.h specify the latest version of the installed
+library.  However, it is recommended that the integer values for FI_MAJOR_VERSION
+and FI_MINOR_VERSION be used, rather than referencing the enum types in order
+to ensure compatibiliy with future versions of the library.  This protects
+against the application being built from source against a newer version of the
+library that introduces new fields to data structures, which would not be
+initialized by the application.
+.PP
 Either node, service, or hints must be provided.  If hints are provided, the
 operation will be controlled by hints.ai_flags.  If FI_PASSIVE is
 specified, the call will resolve address information for use on the

diff --git a/prov/ibverbs/src/fi_verbs.c b/prov/ibverbs/src/fi_verbs.c
@@ -208,8 +208,8 @@ static int ibv_fi_to_rai(struct fi_info *fi, uint64_t flags, struct rdma_addrinf
  	return 0;
  }
 
-static int ibv_getinfo(const char *node, const char *service, uint64_t flags,
-		       struct fi_info *hints, struct fi_info **info)
+static int ibv_getinfo(int version, const char *node, const char *service,
+		       uint64_t flags, struct fi_info *hints, struct fi_info **info)
 {
 	struct rdma_addrinfo rai_hints, *rai;
 	struct fi_info *fi;

diff --git a/prov/psm/src/psmx_init.c b/prov/psm/src/psmx_init.c
@@ -69,8 +69,8 @@ static int psmx_reserve_tag_bits(int *ep_cap, uint64_t *max_tag_value)
 	return 0;
 }
 
-static int psmx_getinfo(const char *node, const char *service, uint64_t flags,
-			struct fi_info *hints, struct fi_info **info)
+static int psmx_getinfo(int version, const char *node, const char *service,
+			uint64_t flags, struct fi_info *hints, struct fi_info **info)
 {
 	struct fi_info *psmx_info;
 	struct fi_ep_attr *ep_attr;

diff --git a/prov/sockets/src/sock.c b/prov/sockets/src/sock.c
@@ -37,19 +37,21 @@
 #include "sock.h"
 
 
-static int sock_getinfo(const char *node, const char *service, uint64_t flags,
-			struct fi_info *hints, struct fi_info **info)
+static int sock_getinfo(int version, const char *node, const char *service,
+			uint64_t flags, struct fi_info *hints, struct fi_info **info)
 {
 	if (hints) {
 		switch (hints->type) {
 		case FID_RDM:
-			return sock_rdm_getinfo(node, service, flags, hints, info);
+			return sock_rdm_getinfo(version, node, service, flags,
+						hints, info);
 		default:
 			return -FI_ENODATA;
 		}
 	} else {
 		/* Call all socket endpoint providers. */
-		return sock_rdm_getinfo(node, service, flags, hints, info);
+		return sock_rdm_getinfo(version, node, service, flags,
+					hints, info);
 	}
 
 	return -FI_ENODATA;

diff --git a/prov/sockets/src/sock.h b/prov/sockets/src/sock.h
@@ -126,20 +126,20 @@ struct sock_ep {
 	struct sock_domain	*dom;
 };
 
-int sock_rdm_getinfo(const char *node, const char *service, uint64_t flags,
-		     struct fi_info *hints, struct fi_info **info);
+int sock_rdm_getinfo(int version, const char *node, const char *service,
+		uint64_t flags, struct fi_info *hints, struct fi_info **info);
 int sock_av_open(struct fid_domain *domain, struct fi_av_attr *attr,
-		 struct fid_av **av, void *context);
+		struct fid_av **av, void *context);
 int sock_cntr_open(struct fid_domain *domain, struct fi_cntr_attr *attr,
-		   struct fid_cntr **cntr, void *context);
+		struct fid_cntr **cntr, void *context);
 int sock_domain(struct fid_fabric *fabric, struct fi_info *info,
 		struct fid_domain **dom, void *context);
 int sock_eq_open(struct fid_domain *domain, struct fi_eq_attr *attr,
-		 struct fid_eq **eq, void *context);
+		struct fid_eq **eq, void *context);
 int sock_rdm_ep(struct fid_domain *domain, struct fi_info *info,
 		struct fid_ep **ep, void *context);
 int sock_poll_open(struct fid_domain *domain, struct fi_poll_attr *attr,
-		   struct fid_poll **pollset);
+		struct fid_poll **pollset);
 int sock_wait_open(struct fid_domain *domain, struct fi_wait_attr *attr,
-		   struct fid_wait **waitset);
+		struct fid_wait **waitset);
 
diff --git a/prov/sockets/src/sock_rdm.c b/prov/sockets/src/sock_rdm.c
@@ -59,8 +59,8 @@
 //static char def_recv_sge[16] = "4";
 //static char def_inline_data[16] = "64";
 
-int sock_rdm_getinfo(const char *node, const char *service, uint64_t flags,
-		     struct fi_info *hints, struct fi_info **info)
+int sock_rdm_getinfo(int version, const char *node, const char *service,
+		     uint64_t flags, struct fi_info *hints, struct fi_info **info)
 {
 	return -FI_ENODATA;
 }

diff --git a/src/fabric.c b/src/fabric.c
@@ -150,11 +150,12 @@ int fi_read_file(const char *dir, const char *file, char *buf, size_t size)
 	return len;
 }
 
-int fi_version_register(int maj_ver, int min_ver, struct fi_ops_prov *ops)
+int fi_version_register(int version, struct fi_ops_prov *ops)
 {
 	struct fi_prov *prov;
 
-	if (maj_ver != FI_MAJOR_VERSION || min_ver < FI_MINOR_VERSION)
+	if (FI_MAJOR(version) != FI_MAJOR_VERSION ||
+	    FI_MINOR(version) > FI_MINOR_VERSION)
 		return -FI_ENOSYS;
 
 	prov = calloc(sizeof *prov, 1);
@@ -215,8 +216,8 @@ static void __attribute__((destructor)) fi_fini(void)
 	sock_fini();
 }
 
-int fi_getinfo(const char *node, const char *service, uint64_t flags,
-	       struct fi_info *hints, struct fi_info **info)
+int fi_getinfo(int version, const char *node, const char *service,
+	       uint64_t flags, struct fi_info *hints, struct fi_info **info)
 {
 	struct fi_prov *prov;
 	struct fi_info *tail, *cur;
@@ -230,7 +231,8 @@ int fi_getinfo(const char *node, const char *service, uint64_t flags,
 		if (!prov->ops->getinfo)
 			continue;
 
-		ret = prov->ops->getinfo(node, service, flags, hints, &cur);
+		ret = prov->ops->getinfo(version, node, service, flags,
+					 hints, &cur);
 		if (ret) {
 			if (ret == -FI_ENODATA)
 				continue;