[alarm] update docs to explicitly require 32-bit alarms (#9043)

include/openthread/instance.h

@@ -53,7 +53,7 @@ extern "C" {
  * @note This number versions both OpenThread platform and user APIs.
  *
  */
-#define OPENTHREAD_API_VERSION (320)
+#define OPENTHREAD_API_VERSION (321)
 
 /**
  * @addtogroup api-instance

include/openthread/platform/alarm-micro.h

@@ -53,6 +53,8 @@ extern "C" {
 /**
  * Set the alarm to fire at @p aDt microseconds after @p aT0.
  *
+ * For both @p aT0 and @p aDt, the platform MUST support all values in [0, 2^32-1].
+ *
  * @param[in]  aInstance  The OpenThread instance structure.
  * @param[in]  aT0        The reference time.
  * @param[in]  aDt        The time delay in microseconds from @p aT0.
@@ -71,6 +73,9 @@ void otPlatAlarmMicroStop(otInstance *aInstance);
 /**
  * Get the current time.
  *
+ * The current time MUST represent a free-running timer. When maintaining current time, the time value MUST utilize the
+ * entire range [0, 2^32-1] and MUST NOT wrap before 2^32.
+ *
  * @returns  The current time in microseconds.
  *
  */

include/openthread/platform/alarm-milli.h

@@ -56,6 +56,8 @@ extern "C" {
 /**
  * Set the alarm to fire at @p aDt milliseconds after @p aT0.
  *
+ * For both @p aT0 and @p aDt, the platform MUST support all values in [0, 2^32-1].
+ *
  * @param[in] aInstance  The OpenThread instance structure.
  * @param[in] aT0        The reference time.
  * @param[in] aDt        The time delay in milliseconds from @p aT0.
@@ -72,6 +74,9 @@ void otPlatAlarmMilliStop(otInstance *aInstance);
 /**
  * Get the current time.
  *
+ * The current time MUST represent a free-running timer. When maintaining current time, the time value MUST utilize the
+ * entire range [0, 2^32-1] and MUST NOT wrap before 2^32.
+ *
  * @returns The current time in milliseconds.
  */
 uint32_t otPlatAlarmMilliGetNow(void);