env: return fd from spdk_pci_device_claim()

This allows users of this interface to then close the fd
when they want to release the claim.

This prepares for calling spdk_pci_device_claim() in the
nvme driver to cover not just the bdev_nvme driver but all
of our nvme example and test applications as well.  We'll
want the fd returned so that we can properly close it during
detach (including hotplug) use cases.

Signed-off-by: Jim Harris <james.r.harris@intel.com>
Change-Id: I8b149cc4e778ba31c0e7045b858c8a1561b6b7af

Reviewed-on: https://review.gerrithub.io/385523
Reviewed-by: Dariusz Stojaczyk <dariuszx.stojaczyk@intel.com>
Tested-by: SPDK Automated Test System <sys_sgsw@intel.com>
Reviewed-by: Daniel Verkamp <daniel.verkamp@intel.com>
Reviewed-by: Ben Walker <benjamin.walker@intel.com>

include/spdk/env.h

@@ -345,6 +345,20 @@ struct spdk_pci_id spdk_pci_device_get_id(struct spdk_pci_device *dev);
 int spdk_pci_device_get_socket_id(struct spdk_pci_device *dev);
 
 int spdk_pci_device_get_serial_number(struct spdk_pci_device *dev, char *sn, size_t len);
+
+/**
+ * Claim a PCI device for exclusive SPDK userspace access.
+ *
+ * Uses F_SETLK on a shared memory file with the PCI address embedded in its name.
+ *  As long as this file remains open with the lock acquired, other processes will
+ *  not be able to successfully call this function on the same PCI device.
+ *
+ * \param pci_addr PCI address of the device to claim
+ *
+ * \return -1 if the device has already been claimed, an fd otherwise.  This fd
+ *	   should be closed when the application no longer needs access to the
+ *	   PCI device (including when it is hot removed).
+ */
 int spdk_pci_device_claim(const struct spdk_pci_addr *pci_addr);
 void spdk_pci_device_detach(struct spdk_pci_device *device);
 

lib/bdev/nvme/bdev_nvme.c

@@ -742,7 +742,7 @@ probe_cb(void *cb_ctx, const struct spdk_nvme_transport_id *trid,
 			return false;
 		}
 
-		if (spdk_pci_device_claim(&pci_addr) != 0) {
+		if (spdk_pci_device_claim(&pci_addr) < 0) {
 			return false;
 		}
 	}

lib/copy/ioat/copy_engine_ioat.c

@@ -248,7 +248,7 @@ probe_cb(void *cb_ctx, struct spdk_pci_device *pci_dev)
 	}
 
 	/* Claim the device in case conflict with other process */
-	if (spdk_pci_device_claim(&pci_addr) != 0) {
+	if (spdk_pci_device_claim(&pci_addr) < 0) {
 		return false;
 	}
 

lib/env_dpdk/pci.c

@@ -495,7 +495,7 @@ spdk_pci_device_claim(const struct spdk_pci_addr *pci_addr)
 	*(int *)dev_map = (int)getpid();
 	munmap(dev_map, sizeof(int));
 	/* Keep dev_fd open to maintain the lock. */
-	return 0;
+	return dev_fd;
 }
 #endif /* __linux__ */
 

test/lib/env/pci/pci_ut.c

@@ -51,7 +51,7 @@ pci_test(void)
 	pci_addr.func = 1;
 
 	rc = spdk_pci_device_claim(&pci_addr);
-	CU_ASSERT(rc == 0);
+	CU_ASSERT(rc >= 0);
 
 	childPid = fork();
 	CU_ASSERT(childPid >= 0);