[random] introduce template-based NonCrypto random APIs (openthread#13142)

This commit introduces a new set of template-based APIs for
non-cryptographic random number generation in the `Random::NonCrypto`
namespace. These new methods provide a cleaner, type-safe, and more
robust interface compared to the previous methods.

Key additions:
- `Generate<UintType>()`: Returns a random value of the given
  unsigned integer type (`uint8_t`, `uint16_t`, or `uint32_t`).
- `GenerateUpToExcluding<UintType>(aMax)`: Returns a random value in
  the range `[0, aMax)`.
- `GenerateFromMinUpToExcluding<UintType>(aMin, aMax)`: Returns a
  random value in the range `[aMin, aMax)`.
- `GenerateInClosedRange<UintType>(aMin, aMax)`: Returns a random
  value in the closed range `[aMin, aMax]`.

The introduction of `GenerateInClosedRange` is an improvement as it
safely handles ranges up to the maximum value of the integer type
(e.g., `0xffff`) without the risk of overflow.

All call sites across the OpenThread core stack and tests have been
updated to adopt these new APIs. The public `otRandomNonCrypto`
functions are also updated to leverage the new internal methods.

Doxygen documentation is added for all new template methods,
detailing their behavior, including edge cases where the upper bound
is smaller than or equal to the lower bound.

Author: abtink

src/core/api/random_noncrypto_api.cpp

@@ -37,25 +37,25 @@
 
 using namespace ot;
 
-uint32_t otRandomNonCryptoGetUint32(void) { return Random::NonCrypto::GetUint32(); }
+uint32_t otRandomNonCryptoGetUint32(void) { return Random::NonCrypto::Generate<uint32_t>(); }
 
-uint8_t otRandomNonCryptoGetUint8(void) { return Random::NonCrypto::GetUint8(); }
+uint8_t otRandomNonCryptoGetUint8(void) { return Random::NonCrypto::Generate<uint8_t>(); }
 
-uint16_t otRandomNonCryptoGetUint16(void) { return Random::NonCrypto::GetUint16(); }
+uint16_t otRandomNonCryptoGetUint16(void) { return Random::NonCrypto::Generate<uint16_t>(); }
 
 uint8_t otRandomNonCryptoGetUint8InRange(uint8_t aMin, uint8_t aMax)
 {
-    return Random::NonCrypto::GetUint8InRange(aMin, aMax);
+    return Random::NonCrypto::GenerateFromMinUpToExcluding(aMin, aMax);
 }
 
 uint16_t otRandomNonCryptoGetUint16InRange(uint16_t aMin, uint16_t aMax)
 {
-    return Random::NonCrypto::GetUint16InRange(aMin, aMax);
+    return Random::NonCrypto::GenerateFromMinUpToExcluding(aMin, aMax);
 }
 
 uint32_t otRandomNonCryptoGetUint32InRange(uint32_t aMin, uint32_t aMax)
 {
-    return Random::NonCrypto::GetUint32InRange(aMin, aMax);
+    return Random::NonCrypto::GenerateFromMinUpToExcluding(aMin, aMax);
 }
 
 void otRandomNonCryptoFillBuffer(uint8_t *aBuffer, uint16_t aSize) { Random::NonCrypto::FillBuffer(aBuffer, aSize); }

src/core/backbone_router/bbr_leader.cpp

@@ -63,13 +63,7 @@ void Config::AdjustMlrTimeout(void)
 
 uint16_t Config::SelectRandomReregistrationDelay(void) const
 {
-    uint16_t delay = 1;
-
-    VerifyOrExit(mReregistrationDelay > 1);
-    delay = 1 + Random::NonCrypto::GetUint16InRange(0, mReregistrationDelay);
-
-exit:
-    return delay;
+    return Random::NonCrypto::GenerateInClosedRange<uint16_t>(1, mReregistrationDelay);
 }
 
 #if OT_SHOULD_LOG_AT(OT_LOG_LEVEL_INFO)

src/core/backbone_router/bbr_local.cpp

@@ -47,7 +47,7 @@ Local::Local(Instance &aInstance)
     : InstanceLocator(aInstance)
     , mIsServiceAdded(false)
     , mState(kStateDisabled)
-    , mSequenceNumber(Random::NonCrypto::GetUint8() % 127)
+    , mSequenceNumber(Random::NonCrypto::GenerateUpToExcluding<uint8_t>(127))
     , mRegistrationJitter(kDefaultRegistrationJitter)
     , mReregistrationDelay(kDefaultRegistrationDelay)
     , mRegistrationTimeout(0)
@@ -266,8 +266,7 @@ void Local::UpdateState(void)
         }
         else
         {
-            mRegistrationTimeout =
-                1 + Random::NonCrypto::GetUint16InRange(0, static_cast<uint16_t>(mRegistrationJitter));
+            mRegistrationTimeout = Random::NonCrypto::GenerateInClosedRange<uint16_t>(1, mRegistrationJitter);
             Get<TimeTicker>().RegisterReceiver(TimeTicker::kBbrLocal);
         }
     }

src/core/border_router/dhcp6_pd_client.cpp

@@ -120,7 +120,7 @@ void Dhcp6PdClient::EnterState(State aState)
     case kStateToSolicit:
         ClearServerDuid();
         ClearPdPrefix();
-        mTimer.Start(Random::NonCrypto::GetUint32InRange(0, kMaxDelayFirstSolicit));
+        mTimer.Start(Random::NonCrypto::GenerateUpToExcluding(kMaxDelayFirstSolicit));
         break;
 
     case kStateSoliciting:
@@ -1183,11 +1183,11 @@ uint32_t Dhcp6PdClient::RetxTracker::AddJitter(uint32_t aValue, JitterMode aJitt
     switch (aJitterMode)
     {
     case kPositiveJitter:
-        randomizedValue += Random::NonCrypto::GetUint32InRange(0, jitter);
+        randomizedValue += Random::NonCrypto::GenerateUpToExcluding<uint32_t>(jitter);
         break;
 
     case kFullJitter:
-        randomizedValue += Random::NonCrypto::GetUint32InRange(0, 2 * jitter) - jitter;
+        randomizedValue += Random::NonCrypto::GenerateUpToExcluding<uint32_t>(2 * jitter) - jitter;
         break;
     }
 

src/core/border_router/routing_manager.cpp

@@ -986,7 +986,7 @@ void RoutingManager::OmrPrefixManager::Evaluate(void)
         {
         case kNotAdded:
         {
-            uint32_t delay = Random::NonCrypto::GetUint32InRange(kMinDelayToAdd, kMaxDelayToAdd);
+            uint32_t delay = Random::NonCrypto::GenerateInClosedRange(kMinDelayToAdd, kMaxDelayToAdd);
 
             mLocalInNetDataState = kToAdd;
             mTimer.Start(delay);

src/core/border_router/rx_ra_tracker.cpp

@@ -1806,7 +1806,7 @@ void RxRaTracker::RsSender::Start(void)
 
     VerifyOrExit(!IsInProgress());
 
-    delay = Random::NonCrypto::GetUint32InRange(0, kMaxStartDelay);
+    delay = Random::NonCrypto::GenerateUpToExcluding(kMaxStartDelay);
 
     LogInfo("RsSender: Starting - will send first RS in %lu msec", ToUlong(delay));
 

src/core/coap/coap.cpp

@@ -124,7 +124,7 @@ CoapBase::CoapBase(Instance &aInstance, Transmitter aTransmitter)
     , mResponseCache(aInstance)
     , mResourceHandler(nullptr)
     , mTransmitter(aTransmitter)
-    , mMessageId(Random::NonCrypto::GetUint16())
+    , mMessageId(Random::NonCrypto::Generate<uint16_t>())
 #if OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE
     , mLastResponse(nullptr)
 #endif
@@ -2045,8 +2045,8 @@ Error TxParameters::ValidateFor(const Msg &aMsg) const
 
 uint32_t TxParameters::CalculateInitialRetransmissionTimeout(void) const
 {
-    return Random::NonCrypto::GetUint32InRange(
-        mAckTimeout, mAckTimeout * mAckRandomFactorNumerator / mAckRandomFactorDenominator + 1);
+    return Random::NonCrypto::GenerateInClosedRange<uint32_t>(mAckTimeout, mAckTimeout * mAckRandomFactorNumerator /
+                                                                               mAckRandomFactorDenominator);
 }
 
 uint32_t TxParameters::CalculateExchangeLifetime(void) const

src/core/common/random.cpp

@@ -37,6 +37,8 @@
 
 #include "common/code_utils.hpp"
 #include "common/debug.hpp"
+#include "common/num_utils.hpp"
+#include "common/numeric_limits.hpp"
 
 namespace ot {
 namespace Random {
@@ -129,30 +131,64 @@ uint32_t Manager::NonCryptoPrng::GetNext(void)
 
 namespace NonCrypto {
 
-uint8_t GetUint8InRange(uint8_t aMin, uint8_t aMax)
+static uint32_t GenerateInRange(uint32_t aMin, uint32_t aMax)
 {
-    OT_ASSERT(aMax > aMin);
+    uint32_t value;
+    uint32_t range;
 
-    return (aMin + (GetUint8() % (aMax - aMin)));
+    VerifyOrExit(aMin < aMax, value = aMin);
+
+    value = Generate<uint32_t>();
+
+    range = aMax - aMin;
+
+    VerifyOrExit(range < NumericLimits<uint32_t>::kMax);
+
+    value = aMin + (value % (range + 1));
+
+exit:
+    return value;
+}
+
+template <typename UintType> UintType GenerateUpToExcluding(UintType aMax)
+{
+    return GenerateFromMinUpToExcluding<UintType>(0, aMax);
 }
 
-uint16_t GetUint16InRange(uint16_t aMin, uint16_t aMax)
+template <typename UintType> UintType GenerateFromMinUpToExcluding(UintType aMin, UintType aMax)
 {
-    OT_ASSERT(aMax > aMin);
-    return (aMin + (GetUint16() % (aMax - aMin)));
+    if (aMax > 0)
+    {
+        aMax--;
+    }
+
+    return GenerateInClosedRange<UintType>(aMin, aMax);
 }
 
-uint32_t GetUint32InRange(uint32_t aMin, uint32_t aMax)
+template <typename UintType> UintType GenerateInClosedRange(UintType aMin, UintType aMax)
 {
-    OT_ASSERT(aMax > aMin);
-    return (aMin + (GetUint32() % (aMax - aMin)));
+    return static_cast<UintType>(GenerateInRange(aMin, aMax));
 }
 
+// Explicit instantiations
+
+template uint8_t  GenerateUpToExcluding<uint8_t>(uint8_t aMax);
+template uint16_t GenerateUpToExcluding<uint16_t>(uint16_t aMax);
+template uint32_t GenerateUpToExcluding<uint32_t>(uint32_t aMax);
+
+template uint8_t  GenerateFromMinUpToExcluding<uint8_t>(uint8_t aMin, uint8_t aMax);
+template uint16_t GenerateFromMinUpToExcluding<uint16_t>(uint16_t aMin, uint16_t aMax);
+template uint32_t GenerateFromMinUpToExcluding<uint32_t>(uint32_t aMin, uint32_t aMax);
+
+template uint8_t  GenerateInClosedRange<uint8_t>(uint8_t aMin, uint8_t aMax);
+template uint16_t GenerateInClosedRange<uint16_t>(uint16_t aMin, uint16_t aMax);
+template uint32_t GenerateInClosedRange<uint32_t>(uint32_t aMin, uint32_t aMax);
+
 void FillBuffer(uint8_t *aBuffer, uint16_t aSize)
 {
     while (aSize-- != 0)
     {
-        *aBuffer++ = GetUint8();
+        *aBuffer++ = Generate<uint8_t>();
     }
 }
 
@@ -163,7 +199,7 @@ uint32_t AddJitter(uint32_t aValue, uint16_t aJitter)
     VerifyOrExit(aValue != 0);
 
     aJitter = (aJitter <= aValue) ? aJitter : static_cast<uint16_t>(aValue);
-    delay   = aValue + GetUint32InRange(0, 2 * aJitter + 1) - aJitter;
+    delay   = aValue + GenerateUpToExcluding<uint32_t>(2 * aJitter + 1) - aJitter;
 
 exit:
     return delay;

src/core/common/random.hpp

@@ -101,60 +101,53 @@ class Manager : private NonCopyable
 namespace NonCrypto {
 
 /**
- * Generates and returns a random `uint32_t` value.
+ * Generates and returns a random value of a given unsigned integer type.
  *
- * @returns    A random `uint32_t` value.
- */
-inline uint32_t GetUint32(void) { return Manager::NonCryptoGetUint32(); }
-
-/**
- * Generates and returns a random byte.
+ * @tparam UintType  The unsigned integer type to generate (must be `uint8_t`, `uint16_t`, or `uint32_t`).
  *
- * @returns A random `uint8_t` value.
+ * @returns A random `UintType` value.
  */
-inline uint8_t GetUint8(void) { return static_cast<uint8_t>(GetUint32() & 0xff); }
+template <typename UintType> inline UintType Generate(void)
+{
+    static_assert(TypeTraits::IsUint<UintType>::kValue, "UintType must be an unsigned int");
+    static_assert(!TypeTraits::IsSame<UintType, uint64_t>::kValue, "UintType cannot be `uint64_t`");
 
-/**
- * Generates and returns a random `uint16_t` value.
- *
- * @returns A random `uint16_t` value.
- */
-inline uint16_t GetUint16(void) { return static_cast<uint16_t>(GetUint32() & 0xffff); }
+    return static_cast<UintType>(Manager::NonCryptoGetUint32());
+}
 
 /**
- * Generates and returns a random `uint8_t` value within a given range `[aMin, aMax)`.
+ * Generates and returns a random value of a given unsigned integer type within range `[0, aMax)`.
+ *
+ * @tparam UintType  The unsigned integer type to generate (must be `uint8_t`, `uint16_t`, or `uint32_t`).
  *
- * @param[in]  aMin  A minimum value (this value can be included in returned random result).
- * @param[in]  aMax  A maximum value (this value is excluded from returned random result).
+ * @param[in] aMax  The upper bound (exclusive). If zero, zero is returned.
  *
- * @returns    A random `uint8_t` value in the given range (i.e., aMin <= random value < aMax).
+ * @returns A random `UintType` value in the range `[0, aMax)`.
  */
-uint8_t GetUint8InRange(uint8_t aMin, uint8_t aMax);
-
+template <typename UintType> UintType GenerateUpToExcluding(UintType aMax);
 /**
- * Generates and returns a random `uint16_t` value within a given range `[aMin, aMax)`.
+ * Generates and returns a random value of a given unsigned integer type within range `[aMin, aMax)`.
  *
- * @note The returned random value can include the @p aMin value but excludes the @p aMax.
+ * @tparam UintType  The unsigned integer type to generate (must be `uint8_t`, `uint16_t`, or `uint32_t`).
  *
- * @param[in]  aMin  A minimum value (this value can be included in returned random result).
- * @param[in]  aMax  A maximum value (this value is excluded from returned random result).
+ * @param[in] aMin  The lower bound (inclusive).
+ * @param[in] aMax  The upper bound (exclusive). If @p aMax <= @p aMin, @p aMin is returned.
  *
- * @returns    A random `uint16_t` value in the given range (i.e., aMin <= random value < aMax).
+ * @returns A random `UintType` value in the range `[aMin, aMax)`.
  */
-uint16_t GetUint16InRange(uint16_t aMin, uint16_t aMax);
+template <typename UintType> UintType GenerateFromMinUpToExcluding(UintType aMin, UintType aMax);
 
 /**
- * Generates and returns a random `uint32_t` value within a given range `[aMin, aMax)`.
+ * Generates and returns a random value of a given unsigned integer type within a closed range `[aMin, aMax]`.
  *
- * @note The returned random value can include the @p aMin value but excludes the @p aMax.
+ * @tparam UintType  The unsigned integer type to generate (must be `uint8_t`, `uint16_t`, or `uint32_t`).
  *
- * @param[in]  aMin  A minimum value (this value can be included in returned random result).
- * @param[in]  aMax  A maximum value (this value is excluded from returned random result).
+ * @param[in] aMin  The lower bound (inclusive).
+ * @param[in] aMax  The upper bound (inclusive). If @p aMax < @p aMin, @p aMin is returned.
  *
- * @returns    A random `uint32_t` value in the given range (i.e., aMin <= random value < aMax).
+ * @returns A random `UintType` value in the range `[aMin, aMax]`.
  */
-uint32_t GetUint32InRange(uint32_t aMin, uint32_t aMax);
-
+template <typename UintType> UintType GenerateInClosedRange(UintType aMin, UintType aMax);
 /**
  * Fills a given buffer with random bytes.
  *

src/core/common/time_ticker.cpp

@@ -50,7 +50,7 @@ void TimeTicker::RegisterReceiver(Receiver aReceiver)
 
     if (!mTimer.IsRunning())
     {
-        mTimer.Start(Random::NonCrypto::GetUint32InRange(0, kTickInterval + 1));
+        mTimer.Start(Random::NonCrypto::GenerateInClosedRange<uint32_t>(0, kTickInterval));
     }
 }