[PATCH v3 62/65] kvargs: add range conversion handlers

[Stephen Hemminger <stephen@networkplumber.org>]

An argument whose valid range is narrower than the type it is stored in
cannot use the typed handlers, so drivers write a handler of their own
which calls rte_kvargs_to_uint() and stores the result. There are about
25 of these.

They do not report the same way. Of the call sites, 22 reject a bad
value with no message at all, so nothing tells the user what the range
was. Those which do log one each word it differently:

  net/af_xdp:   "Invalid busy_budget, must be >= 0 and <= %u"
  dma/skeleton: "Invalid %s, must be 0..%u"
  net/bnxt:     "Invalid parameter passed to rep_q_r2f devargs."

Add handlers which take the bounds from the caller:

    rte_kvargs_handle_urange
    rte_kvargs_handle_irange

A handler has only one opaque pointer, so the bounds are passed and the
result returned through a structure. As the typed handlers, the result
is written only on success, so seeding it with the default leaves it
alone when the key is absent and when the value is rejected.

A value outside the range is now reported as one which does not fit a
whole type already is, naming the key and the bounds.

kvargs_store_uint() grows a minimum to go with the maximum it already
had; the typed handlers pass zero.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 app/test/test_kvargs.c                 | 43 ++++++++++++++++++
 doc/guides/rel_notes/release_26_11.rst |  6 +++
 lib/kvargs/rte_kvargs.c                | 62 +++++++++++++++++++++-----
 lib/kvargs/rte_kvargs.h                | 57 +++++++++++++++++++++++
 4 files changed, 157 insertions(+), 11 deletions(-)

diff --git a/app/test/test_kvargs.c b/app/test/test_kvargs.c
index 6e84ebf35c..12e1376e86 100644
--- a/app/test/test_kvargs.c
+++ b/app/test/test_kvargs.c
@@ -619,6 +619,48 @@ test_kvargs_to_range(void)
 	return TEST_SUCCESS;
 }
 
+static int
+test_handle_range(void)
+{
+	struct rte_kvargs_urange u = { .min = 1, .max = 10, .val = 7 };
+	struct rte_kvargs_irange s = { .min = -10, .max = 10, .val = -7 };
+	struct rte_kvargs *kvlist;
+
+	TEST_ASSERT_SUCCESS(handle_one(rte_kvargs_handle_urange, "10", &u),
+			    "10 rejected in [1,10]");
+	TEST_ASSERT_EQUAL(u.val, 10U, "wrong value");
+
+	/* Out of range and malformed values leave the result alone. */
+	TEST_ASSERT_FAIL(handle_one(rte_kvargs_handle_urange, "11", &u),
+			 "11 accepted in [1,10]");
+	TEST_ASSERT_EQUAL(u.val, 10U, "target clobbered above the range");
+	TEST_ASSERT_FAIL(handle_one(rte_kvargs_handle_urange, "0", &u),
+			 "0 accepted in [1,10]");
+	TEST_ASSERT_EQUAL(u.val, 10U, "target clobbered below the range");
+	TEST_ASSERT_FAIL(handle_one(rte_kvargs_handle_urange, "x", &u),
+			 "\"x\" accepted");
+	TEST_ASSERT_EQUAL(u.val, 10U, "target clobbered on a bad value");
+
+	TEST_ASSERT_SUCCESS(handle_one(rte_kvargs_handle_irange, "-10", &s),
+			    "-10 rejected in [-10,10]");
+	TEST_ASSERT_EQUAL(s.val, -10, "wrong value");
+	TEST_ASSERT_FAIL(handle_one(rte_kvargs_handle_irange, "-11", &s),
+			 "-11 accepted in [-10,10]");
+	TEST_ASSERT_EQUAL(s.val, -10, "target clobbered below the range");
+
+	/* A key which is not present leaves the seeded default alone. */
+	u.val = 7;
+	kvlist = rte_kvargs_parse("other=1", NULL);
+	TEST_ASSERT_NOT_NULL(kvlist, "parse failed");
+	TEST_ASSERT_SUCCESS(rte_kvargs_process(kvlist, "k",
+					       rte_kvargs_handle_urange, &u),
+			    "processing an absent key failed");
+	rte_kvargs_free(kvlist);
+	TEST_ASSERT_EQUAL(u.val, 7U, "default lost when the key is absent");
+
+	return TEST_SUCCESS;
+}
+
 static struct unit_test_suite kvargs_test_suite  = {
 	.suite_name = "Kvargs Unit Test Suite",
 	.setup = NULL,
@@ -651,6 +693,7 @@ static struct unit_test_suite kvargs_test_suite  = {
 		TEST_CASE(test_handle_bool),
 		TEST_CASE(test_handle_socket_id),
 		TEST_CASE(test_kvargs_to_range),
+		TEST_CASE(test_handle_range),
 		TEST_CASES_END() /**< NULL terminate unit test array */
 	}
 };
diff --git a/doc/guides/rel_notes/release_26_11.rst b/doc/guides/rel_notes/release_26_11.rst
index 27b3fe4253..e2cab9a484 100644
--- a/doc/guides/rel_notes/release_26_11.rst
+++ b/doc/guides/rel_notes/release_26_11.rst
@@ -164,6 +164,12 @@ New Features
   ``rte_kvargs_to_hex`` for the cases where a driver needs a narrower range
   than the target type allows.
 
+  Added ``rte_kvargs_handle_urange`` and ``rte_kvargs_handle_irange``,
+  which take the bounds and return the result through a
+  ``struct rte_kvargs_urange`` or ``struct rte_kvargs_irange``. An
+  argument whose valid range is narrower than its storage type no longer
+  needs a handler of its own, and a value outside the range is reported
+  as one which does not fit a whole type already is.
 
 Removed Items
 -------------
diff --git a/lib/kvargs/rte_kvargs.c b/lib/kvargs/rte_kvargs.c
index 22bde9616c..7d85e60092 100644
--- a/lib/kvargs/rte_kvargs.c
+++ b/lib/kvargs/rte_kvargs.c
@@ -554,17 +554,19 @@ rte_kvargs_to_hex(const char *value, uint64_t max, uint64_t *result)
  */
 static int
 kvargs_store_uint(const char *key, const char *value, void *opaque,
-		  uint64_t max, uint64_t *val)
+		  uint64_t min, uint64_t max, uint64_t *val)
 {
 	int ret;
 
 	if (opaque == NULL)
 		return -EINVAL;
 
-	ret = rte_kvargs_to_uint(value, 0, max, val);
+	ret = rte_kvargs_to_uint(value, min, max, val);
 	if (ret < 0)
-		KVARGS_LOG(ERR, "invalid value \"%s\" for key \"%s\", expected 0..%" PRIu64,
-			   value != NULL ? value : "", key != NULL ? key : "", max);
+		KVARGS_LOG(ERR,
+			   "invalid value \"%s\" for key \"%s\", expected %" PRIu64 "..%" PRIu64,
+			   value != NULL ? value : "", key != NULL ? key : "",
+			   min, max);
 
 	return ret;
 }
@@ -595,7 +597,7 @@ rte_kvargs_handle_u8(const char *key, const char *value, void *opaque)
 	uint64_t val;
 	int ret;
 
-	ret = kvargs_store_uint(key, value, opaque, UINT8_MAX, &val);
+	ret = kvargs_store_uint(key, value, opaque, 0, UINT8_MAX, &val);
 	if (ret == 0)
 		*(uint8_t *)opaque = (uint8_t)val;
 
@@ -609,7 +611,7 @@ rte_kvargs_handle_u16(const char *key, const char *value, void *opaque)
 	uint64_t val;
 	int ret;
 
-	ret = kvargs_store_uint(key, value, opaque, UINT16_MAX, &val);
+	ret = kvargs_store_uint(key, value, opaque, 0, UINT16_MAX, &val);
 	if (ret == 0)
 		*(uint16_t *)opaque = (uint16_t)val;
 
@@ -623,7 +625,7 @@ rte_kvargs_handle_u32(const char *key, const char *value, void *opaque)
 	uint64_t val;
 	int ret;
 
-	ret = kvargs_store_uint(key, value, opaque, UINT32_MAX, &val);
+	ret = kvargs_store_uint(key, value, opaque, 0, UINT32_MAX, &val);
 	if (ret == 0)
 		*(uint32_t *)opaque = (uint32_t)val;
 
@@ -637,7 +639,7 @@ rte_kvargs_handle_u64(const char *key, const char *value, void *opaque)
 	uint64_t val;
 	int ret;
 
-	ret = kvargs_store_uint(key, value, opaque, UINT64_MAX, &val);
+	ret = kvargs_store_uint(key, value, opaque, 0, UINT64_MAX, &val);
 	if (ret == 0)
 		*(uint64_t *)opaque = (uint64_t)val;
 
@@ -651,7 +653,7 @@ rte_kvargs_handle_uint(const char *key, const char *value, void *opaque)
 	uint64_t val;
 	int ret;
 
-	ret = kvargs_store_uint(key, value, opaque, UINT_MAX, &val);
+	ret = kvargs_store_uint(key, value, opaque, 0, UINT_MAX, &val);
 	if (ret == 0)
 		*(unsigned int *)opaque = (unsigned int)val;
 
@@ -665,7 +667,7 @@ rte_kvargs_handle_size(const char *key, const char *value, void *opaque)
 	uint64_t val;
 	int ret;
 
-	ret = kvargs_store_uint(key, value, opaque, SIZE_MAX, &val);
+	ret = kvargs_store_uint(key, value, opaque, 0, SIZE_MAX, &val);
 	if (ret == 0)
 		*(size_t *)opaque = (size_t)val;
 
@@ -763,7 +765,7 @@ rte_kvargs_handle_ulong(const char *key, const char *value, void *opaque)
 	uint64_t val;
 	int ret;
 
-	ret = kvargs_store_uint(key, value, opaque, ULONG_MAX, &val);
+	ret = kvargs_store_uint(key, value, opaque, 0, ULONG_MAX, &val);
 	if (ret == 0)
 		*(unsigned long *)opaque = (unsigned long)val;
 
@@ -873,3 +875,41 @@ rte_kvargs_handle_socket_id(const char *key, const char *value, void *opaque)
 
 	return ret;
 }
+
+RTE_EXPORT_EXPERIMENTAL_SYMBOL(rte_kvargs_handle_urange, 26.11)
+int
+rte_kvargs_handle_urange(const char *key, const char *value, void *opaque)
+{
+	struct rte_kvargs_urange *range = opaque;
+	uint64_t val;
+	int ret;
+
+	if (range == NULL)
+		return -EINVAL;
+
+	ret = kvargs_store_uint(key, value, opaque, range->min, range->max,
+				&val);
+	if (ret == 0)
+		range->val = val;
+
+	return ret;
+}
+
+RTE_EXPORT_EXPERIMENTAL_SYMBOL(rte_kvargs_handle_irange, 26.11)
+int
+rte_kvargs_handle_irange(const char *key, const char *value, void *opaque)
+{
+	struct rte_kvargs_irange *range = opaque;
+	int64_t val;
+	int ret;
+
+	if (range == NULL)
+		return -EINVAL;
+
+	ret = kvargs_store_int(key, value, opaque, range->min, range->max,
+			       &val);
+	if (ret == 0)
+		range->val = val;
+
+	return ret;
+}
diff --git a/lib/kvargs/rte_kvargs.h b/lib/kvargs/rte_kvargs.h
index fe18841709..ac79640085 100644
--- a/lib/kvargs/rte_kvargs.h
+++ b/lib/kvargs/rte_kvargs.h
@@ -487,6 +487,63 @@ int rte_kvargs_to_int(const char *value, int64_t min, int64_t max,
 __rte_experimental
 int rte_kvargs_to_hex(const char *value, uint64_t max, uint64_t *result);
 
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice.
+ *
+ * Range and result for rte_kvargs_handle_urange().
+ */
+struct rte_kvargs_urange {
+	uint64_t min;	/**< Smallest acceptable value, inclusive. */
+	uint64_t max;	/**< Largest acceptable value, inclusive. */
+	uint64_t val;	/**< The result, written only on success. */
+};
+
+/** Range and result for rte_kvargs_handle_irange(). */
+struct rte_kvargs_irange {
+	int64_t min;	/**< Smallest acceptable value, inclusive. */
+	int64_t max;	/**< Largest acceptable value, inclusive. */
+	int64_t val;	/**< The result, written only on success. */
+};
+
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice.
+ *
+ * Convert a key/value pair to an unsigned integer in a range.
+ *
+ * As rte_kvargs_handle_u8(), except that the bounds are given by the
+ * caller rather than by the target type. This is for an argument whose
+ * valid range is narrower than the type it is stored in.
+ *
+ * The bounds are passed and the result returned through the same
+ * structure, since a handler has only one opaque pointer. Seed ``val``
+ * with the default: it is left alone when the key is absent and when
+ * the value is rejected.
+ *
+ * @param key
+ *   The key, used for error reporting only. May be NULL.
+ * @param value
+ *   The value to convert.
+ * @param opaque
+ *   Pointer to a ``struct rte_kvargs_urange`` holding the range. On
+ *   success its ``val`` is set, on error it is left unmodified.
+ *
+ * @return
+ *   - 0 on success.
+ *   - -EINVAL if the value is missing or malformed, or if @p opaque is NULL.
+ *   - -ERANGE if the value is outside the range.
+ */
+__rte_experimental
+int rte_kvargs_handle_urange(const char *key, const char *value, void *opaque);
+
+/**
+ * Convert a value to a signed integer in a range, taking a
+ * ``struct rte_kvargs_irange``. See rte_kvargs_handle_urange().
+ */
+__rte_experimental
+int rte_kvargs_handle_irange(const char *key, const char *value, void *opaque);
+
 #ifdef __cplusplus
 }
 #endif
-- 
2.53.0