env: deprecate phys_addr param in spdk_*malloc()

Historically, all memory returned from spdk_*malloc()
used to be physically contiguous, hence it could be
addressed by offsetting just a single physical address.

Since DPDK dynamic memory management came along, the
above is no longer true. Memory returned from spdk_*malloc()
doesn't have to be physically contiguous anymore. The
phys_addr returned from spdk_*malloc() only applies to
the beginning of the allocated buffer and user can't
possibly know how big that "beginning" is.

The phys_addr parameter in spdk_*malloc() is useless on
its own in most cases and only suggests that the returned
buffer is physically contiguous, which is wrong.

This information can be returned from spdk_vtophys(),
which is the only safe way to retrieve physical addresses.
That's why phys_addr param in spdk_*malloc() is now
deprecated.

Change-Id: I934292f7db28b869b05caca4cb5c68c436e228d4
Signed-off-by: Darek Stojaczyk <dariusz.stojaczyk@intel.com>
Reviewed-on: https://review.gerrithub.io/c/spdk/spdk/+/448168
Tested-by: SPDK CI Jenkins <sys_sgci@intel.com>
Reviewed-by: Changpeng Liu <changpeng.liu@intel.com>
Reviewed-by: Jim Harris <james.r.harris@intel.com>

CHANGELOG.md

@@ -52,6 +52,11 @@ The size of a shared receive queue is defined by transport configuration file pa
 `MaxSRQDepth` and `nvmf_create_transport` RPC method parameter `max_srq_depth`.
 Default size is 4096.
 
+### env
+
+The `phys_addr` parameter in spdk_malloc() and spdk_zmalloc() has been deprecated.
+For retrieving physical addresses, spdk_vtophys() should be used instead.
+
 ## v19.01:
 
 ### ocf bdev

include/spdk/env.h

@@ -98,7 +98,8 @@ struct spdk_env_opts {
  * buffer is suitably aligned (in the same manner as malloc()). Otherwise, the
  * allocated buffer is aligned to the multiple of align. In this case, it must
  * be a power of two.
- * \param phys_addr A pointer to the variable to hold the physical address of
+ * \param phys_addr **Deprecated**. Please use spdk_vtophys() for retrieving physical
+ * addresses. A pointer to the variable to hold the physical address of
  * the allocated buffer is passed. If NULL, the physical address is not returned.
  * \param socket_id Socket ID to allocate memory on, or SPDK_ENV_SOCKET_ID_ANY
  * for any socket.
@@ -118,7 +119,8 @@ void *spdk_malloc(size_t size, size_t align, uint64_t *phys_addr, int socket_id,
  * buffer is suitably aligned (in the same manner as malloc()). Otherwise, the
  * allocated buffer is aligned to the multiple of align. In this case, it must
  * be a power of two.
- * \param phys_addr A pointer to the variable to hold the physical address of
+ * \param phys_addr **Deprecated**. Please use spdk_vtophys() for retrieving physical
+ * addresses. A pointer to the variable to hold the physical address of
  * the allocated buffer is passed. If NULL, the physical address is not returned.
  * \param socket_id Socket ID to allocate memory on, or SPDK_ENV_SOCKET_ID_ANY
  * for any socket.

lib/env_dpdk/env.c

@@ -71,6 +71,9 @@ spdk_malloc(size_t size, size_t align, uint64_t *phys_addr, int socket_id, uint3
 
 	void *buf = rte_malloc_socket(NULL, size, align, socket_id);
 	if (buf && phys_addr) {
+#ifdef DEBUG
+		fprintf(stderr, "phys_addr param in spdk_*malloc() is deprecated\n");
+#endif
 		*phys_addr = virt_to_phys(buf);
 	}
 	return buf;