From 504edb1ea568a9b8485848b846d271e5785c27f3 Mon Sep 17 00:00:00 2001 From: Ben Walker Date: Mon, 1 Nov 2021 13:04:04 -0700 Subject: [PATCH] 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: Ben Walker Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/10100 Community-CI: Mellanox Build Bot Community-CI: Broadcom CI Tested-by: SPDK CI Jenkins Reviewed-by: Changpeng Liu Reviewed-by: Shuhei Matsumoto Reviewed-by: Aleksey Marchuk Reviewed-by: Jim Harris --- include/spdk/nvme.h | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/include/spdk/nvme.h b/include/spdk/nvme.h index a418d339d8..57f80e1f0a 100644 --- a/include/spdk/nvme.h +++ b/include/spdk/nvme.h @@ -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.