Commit 504edb1e authored by Ben Walker's avatar Ben Walker Committed by Jim Harris
Browse files

nvme: Update documentation for spdk_nvme_ctrlr_get_num_ns 



Clearly indicate that the value returned by this function has been
misinterpreted so many times that it has been rendered worthless.

Instead, software can use the functions to iterate the active namespaces
as a replacement.

Change-Id: I355f123eac0d33d63716cc333dc674d2ef226dc4
Signed-off-by: default avatarBen Walker <benjamin.walker@intel.com>
Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/10100


Community-CI: Mellanox Build Bot
Community-CI: Broadcom CI <spdk-ci.pdl@broadcom.com>
Tested-by: default avatarSPDK CI Jenkins <sys_sgci@intel.com>
Reviewed-by: default avatarChangpeng Liu <changpeng.liu@intel.com>
Reviewed-by: default avatarShuhei Matsumoto <shuhei.matsumoto.xt@hitachi.com>
Reviewed-by: default avatarAleksey Marchuk <alexeymar@mellanox.com>
Reviewed-by: default avatarJim Harris <james.r.harris@intel.com>
parent 7ffc8833

include/spdk/nvme.h

+8 −1
Original line number Diff line number Diff line
@@ -1240,7 +1240,7 @@ union spdk_nvme_bpinfo_register spdk_nvme_ctrlr_get_regs_bpinfo(struct spdk_nvme 
uint64_t spdk_nvme_ctrlr_get_pmrsz(struct spdk_nvme_ctrlr *ctrlr);



/**

 * Get the number of namespaces for the given NVMe controller.

 * Get the maximum NSID value that will ever be used for the given controller

 *

 * This function is thread safe and can be called at any point while the

 * controller is attached to the SPDK NVMe driver.
@@ -1248,6 +1248,13 @@ uint64_t spdk_nvme_ctrlr_get_pmrsz(struct spdk_nvme_ctrlr *ctrlr); 
 * This is equivalent to calling spdk_nvme_ctrlr_get_data() to get the

 * spdk_nvme_ctrlr_data and then reading the nn field.

 *

 * The NN field in the NVMe specification represents the maximum value that a

 * namespace ID can ever have. Prior to NVMe 1.2, this was also the number of

 * active namespaces, but from 1.2 onward the list of namespaces may be

 * sparsely populated. Unfortunately, the meaning of this field is often

 * misinterpreted by drive manufacturers and NVMe-oF implementers so it is

 * not considered reliable. AVOID USING THIS FUNCTION WHENEVER POSSIBLE.

 *

 * \param ctrlr Opaque handle to NVMe controller.

 *

 * \return the number of namespaces.