[PATCH 03/18] eal: add 32 bit random number function

[Stephen Hemminger]

Add a function returning a 32 bit random value. Callers that only
need 32 bits currently have to truncate the result of rte_rand(),
which assumes that the low bits of the generator are as good as the
high ones. That happens to hold for the current generator but is not
a property callers should have to know about.

Returning the high bits keeps the function correct for the common
case where a generator has weaker low order bits.

Signed-off-by: Stephen Hemminger <stephen at networkplumber.org>
---
 doc/guides/rel_notes/release_26_11.rst |  2 ++
 lib/eal/common/rte_random.c            | 10 +++++++
 lib/eal/include/rte_random.h           | 39 +++++++++++++++++++-------
 3 files changed, 41 insertions(+), 10 deletions(-)

diff --git a/doc/guides/rel_notes/release_26_11.rst b/doc/guides/rel_notes/release_26_11.rst
index 5852f7acfb..1dc634d504 100644
--- a/doc/guides/rel_notes/release_26_11.rst
+++ b/doc/guides/rel_notes/release_26_11.rst
@@ -58,6 +58,8 @@ New Features
 * **Updated random number generation.**
 
   * The initial seed is now always taken from ``getentropy()``.
+  * Added ``rte_rand32()`` for callers which only need 32 bits and would
+    otherwise have to truncate the result of ``rte_rand()``.
 
 
 Removed Items
diff --git a/lib/eal/common/rte_random.c b/lib/eal/common/rte_random.c
index b036c50349..1368b70e27 100644
--- a/lib/eal/common/rte_random.c
+++ b/lib/eal/common/rte_random.c
@@ -158,6 +158,16 @@ rte_rand(void)
 	return __rte_rand_lfsr258(state);
 }
 
+RTE_EXPORT_SYMBOL(rte_rand32)
+uint32_t
+rte_rand32(void)
+{
+	/* Use the high bits, they are the ones that stay good if the
+	 * underlying generator is ever changed.
+	 */
+	return (uint32_t)(rte_rand() >> 32);
+}
+
 RTE_EXPORT_SYMBOL(rte_rand_max)
 uint64_t
 rte_rand_max(uint64_t upper_bound)
diff --git a/lib/eal/include/rte_random.h b/lib/eal/include/rte_random.h
index 978ecda203..9d3ecc596e 100644
--- a/lib/eal/include/rte_random.h
+++ b/lib/eal/include/rte_random.h
@@ -13,6 +13,8 @@
 
 #include <stdint.h>
 
+#include <rte_compat.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -27,7 +29,7 @@ extern "C" {
  *
  * This function is not multi-thread safe in regards to other
  * rte_srand() calls, nor is it in relation to concurrent rte_rand(),
- * rte_rand_max() or rte_drand() calls.
+ * rte_rand32(), rte_rand_max() or rte_drand() calls.
  *
  * @param seedval
  *   The value of the seed.
@@ -40,9 +42,9 @@ rte_srand(uint64_t seedval);
  *
  * The generator is not cryptographically secure.
  *
- * rte_rand(), rte_rand_max() and rte_drand() are multi-thread safe,
- * with the exception that they may not be called by multiple
- * _unregistered_ non-EAL threads in parallel.
+ * rte_rand(), rte_rand32(), rte_rand_max() and rte_drand() are
+ * multi-thread safe, with the exception that they may not be called
+ * by multiple _unregistered_ non-EAL threads in parallel.
  *
  * @return
  *   A pseudo-random value between 0 and (1<<64)-1.
@@ -50,15 +52,32 @@ rte_srand(uint64_t seedval);
 uint64_t
 rte_rand(void);
 
+/**
+ * Get a 32 bit pseudo-random value.
+ *
+ * Prefer this over truncating the result of rte_rand() since not
+ * every generator produces equally good values in all bit positions.
+ *
+ * The generator is not cryptographically secure.
+ *
+ * This function is multi-thread safe, with the exception that it may
+ * not be called by multiple _unregistered_ non-EAL threads in parallel.
+ *
+ * @return
+ *   A pseudo-random value between 0 and (1<<32)-1.
+ */
+uint32_t
+rte_rand32(void);
+
 /**
  * Generates a pseudo-random number with an upper bound.
  *
  * This function returns an uniformly distributed (unbiased) random
  * number less than a user-specified maximum value.
  *
- * rte_rand(), rte_rand_max() and rte_drand() are multi-thread safe,
- * with the exception that they may not be called by multiple
- * _unregistered_ non-EAL threads in parallel.
+ * rte_rand(), rte_rand32(), rte_rand_max() and rte_drand() are
+ * multi-thread safe, with the exception that they may not be called
+ * by multiple _unregistered_ non-EAL threads in parallel.
  *
  * @param upper_bound
  *   The upper bound of the generated number.
@@ -76,9 +95,9 @@ rte_rand_max(uint64_t upper_bound);
  *
  * The generator is not cryptographically secure.
  *
- * rte_rand(), rte_rand_max() and rte_drand() are multi-thread safe,
- * with the exception that they may not be called by multiple
- * _unregistered_ non-EAL threads in parallel.
+ * rte_rand(), rte_rand32(), rte_rand_max() and rte_drand() are
+ * multi-thread safe, with the exception that they may not be called
+ * by multiple _unregistered_ non-EAL threads in parallel.
  *
  * @return
  *   A pseudo-random value between 0 and 1.0.
-- 
2.53.0