[PATCH v3 01/16] eal: introduce division round up macro

[Joshua Washington <joshwash@google.com>]

A number of drivers define the DIV_ROUND_UP macro -- add it to
rte_common.h so that other code looking to use that functionality
doesn't have to re-define it.

Signed-off-by: Joshua Washington <joshwash@google.com>
---
Changes in v3:
  - Add unit tests in app/test/test_common.c.
  - Add release notes entry.
  - Enhance Doxygen documentation to document parameters and caveats
    (divisor evaluation, non-negative inputs, wraparound).
Changes in v2:
  - Split out patches replacing usages
---
 app/test/test_common.c                 | 10 ++++++++++
 doc/guides/rel_notes/release_26_11.rst |  5 +++++
 lib/eal/include/rte_common.h           | 18 ++++++++++++++++++
 3 files changed, 33 insertions(+)

diff --git a/app/test/test_common.c b/app/test/test_common.c
index 3e1c7df0c1..bce2776ea6 100644
--- a/app/test/test_common.c
+++ b/app/test/test_common.c
@@ -47,6 +47,16 @@ test_macros(int __rte_unused unused_parm)
 		"RTE_MAX");
 	RTE_TEST_ASSERT_EQUAL(RTE_MIN(SMALLER, BIGGER), SMALLER,
 		"RTE_MIN");
+	RTE_TEST_ASSERT_EQUAL(RTE_DIV_ROUND_UP(10, 5), 2,
+		"RTE_DIV_ROUND_UP exact");
+	RTE_TEST_ASSERT_EQUAL(RTE_DIV_ROUND_UP(11, 5), 3,
+		"RTE_DIV_ROUND_UP remainder");
+	RTE_TEST_ASSERT_EQUAL(RTE_DIV_ROUND_UP(0, 5), 0,
+		"RTE_DIV_ROUND_UP n=0");
+	RTE_TEST_ASSERT_EQUAL(RTE_DIV_ROUND_UP(0, 1), 0,
+		"RTE_DIV_ROUND_UP n=0, d=1");
+	RTE_TEST_ASSERT_EQUAL(RTE_DIV_ROUND_UP(5, 1), 5,
+		"RTE_DIV_ROUND_UP d=1");
 
 	RTE_TEST_ASSERT_EQUAL(RTE_PTR_ADD(arr + 1, sizeof(arr[0])), &arr[2],
 		"RTE_PTR_ADD(expr, x)");
diff --git a/doc/guides/rel_notes/release_26_11.rst b/doc/guides/rel_notes/release_26_11.rst
index c8cc86295d..7720fd9f96 100644
--- a/doc/guides/rel_notes/release_26_11.rst
+++ b/doc/guides/rel_notes/release_26_11.rst
@@ -55,6 +55,11 @@ New Features
      Also, make sure to start the actual text at the margin.
      =======================================================
 
+* **Added division round up macro.**
+
+  Added the ``RTE_DIV_ROUND_UP`` macro in ``rte_common.h`` to divide dividend
+  by divisor, rounding up to the nearest integer.
+
 
 Removed Items
 -------------
diff --git a/lib/eal/include/rte_common.h b/lib/eal/include/rte_common.h
index 79d2a0ab93..9707f7e255 100644
--- a/lib/eal/include/rte_common.h
+++ b/lib/eal/include/rte_common.h
@@ -717,6 +717,24 @@ static void __attribute__((destructor(RTE_PRIO(prio)), used)) func(void)
 		(ceil - (v)) > ((v) - floor) ? floor : ceil;	\
 	})
 
+/**
+ * Macro to divide dividend @p n by divisor @p d, rounding up if @p d does not divide @p n.
+ *
+ * @param n
+ *   Dividend. Must be a non-negative integer to round correctly.
+ * @param d
+ *   Divisor. Must be a positive integer. Evaluated twice.
+ * @return
+ *   Result of dividing @p n by @p d, rounded up.
+ *
+ * @note The divisor @p d is evaluated twice. Arguments must not have side effects.
+ * @note Both @p n and @p d must be non-negative to round correctly.
+ * @note The sum @c (n) + (d) - 1 can wrap around if @p n is close to the maximum
+ *       representable value of its type (e.g. RTE_DIV_ROUND_UP(UINT32_MAX, 2)
+ *       on uint32_t wraps to 0).
+ */
+#define RTE_DIV_ROUND_UP(n, d) (((n) + (d) - 1) / (d))
+
 /**
  * Checks if a pointer is aligned to a given power-of-two value
  *
-- 
2.55.0.1082.g2b9226bbc0-goog