Fix #1307, Add time conversion reciprocal functions

Adds the following APIs which are direct reciprocals of the existing
time conversion functions:

OS_time_t OS_TimeFromTotalSeconds(int64 tm)
OS_time_t OS_TimeFromTotalMilliseconds(int64 tm)
OS_time_t OS_TimeFromTotalMicroseconds(int64 tm)
OS_time_t OS_TimeFromTotalNanoseconds(int64 tm)

src/os/inc/osapi-clock.h

@@ -123,6 +123,7 @@ int32 OS_SetLocalTime(const OS_time_t *time_struct);
  * structure was defined with separate seconds/microseconds fields.
  *
  * @sa OS_TimeGetMicrosecondsPart()
+ * @sa OS_TimeFromTotalSeconds()
  *
  * @param[in] tm    Time interval value
  * @returns   Whole number of seconds in time interval
@@ -132,12 +133,31 @@ static inline int64 OS_TimeGetTotalSeconds(OS_time_t tm)
     return (tm.ticks / OS_TIME_TICKS_PER_SECOND);
 }
 
+/*-------------------------------------------------------------------------------------*/
+/**
+ * @brief Get an OS_time_t interval object from an integer number of seconds
+ *
+ * This is the inverse operation of OS_TimeGetTotalSeconds(), converting the
+ * total number of seconds into an OS_time_t value.
+ *
+ * @sa OS_TimeGetTotalSeconds()
+ *
+ * @param[in] tm    Time interval value, in seconds
+ * @returns   OS_time_t value representing the interval
+ */
+static inline OS_time_t OS_TimeFromTotalSeconds(int64 tm)
+{
+    return (OS_time_t) {.ticks = (tm * OS_TIME_TICKS_PER_SECOND)};
+}
+
 /*-------------------------------------------------------------------------------------*/
 /**
  * @brief Get interval from an OS_time_t object normalized to millisecond units
  *
  * Note this refers to the complete interval, not just the fractional part.
  *
+ * @sa OS_TimeFromTotalMilliseconds()
+ *
  * @param[in] tm    Time interval value
  * @returns   Whole number of milliseconds in time interval
  */
@@ -146,12 +166,31 @@ static inline int64 OS_TimeGetTotalMilliseconds(OS_time_t tm)
     return (tm.ticks / OS_TIME_TICKS_PER_MSEC);
 }
 
+/*-------------------------------------------------------------------------------------*/
+/**
+ * @brief Get an OS_time_t interval object from a integer number of milliseconds
+ *
+ * This is the inverse operation of OS_TimeGetTotalMilliseconds(), converting the
+ * total number of milliseconds into an OS_time_t value.
+ *
+ * @sa OS_TimeGetTotalMilliseconds()
+ *
+ * @param[in] tm    Time interval value, in milliseconds
+ * @returns   OS_time_t value representing the interval
+ */
+static inline OS_time_t OS_TimeFromTotalMilliseconds(int64 tm)
+{
+    return (OS_time_t) {.ticks = (tm * OS_TIME_TICKS_PER_MSEC)};
+}
+
 /*-------------------------------------------------------------------------------------*/
 /**
  * @brief Get interval from an OS_time_t object normalized to microsecond units
  *
  * Note this refers to the complete interval, not just the fractional part.
  *
+ * @sa OS_TimeFromTotalMicroseconds()
+ *
  * @param[in] tm    Time interval value
  * @returns   Whole number of microseconds in time interval
  */
@@ -160,6 +199,23 @@ static inline int64 OS_TimeGetTotalMicroseconds(OS_time_t tm)
     return (tm.ticks / OS_TIME_TICKS_PER_USEC);
 }
 
+/*-------------------------------------------------------------------------------------*/
+/**
+ * @brief Get an OS_time_t interval object from a integer number of microseconds
+ *
+ * This is the inverse operation of OS_TimeGetTotalMicroseconds(), converting the
+ * total number of microseconds into an OS_time_t value.
+ *
+ * @sa OS_TimeGetTotalMicroseconds()
+ *
+ * @param[in] tm    Time interval value, in microseconds
+ * @returns   OS_time_t value representing the interval
+ */
+static inline OS_time_t OS_TimeFromTotalMicroseconds(int64 tm)
+{
+    return (OS_time_t) {.ticks = (tm * OS_TIME_TICKS_PER_USEC)};
+}
+
 /*-------------------------------------------------------------------------------------*/
 /**
  * @brief Get interval from an OS_time_t object normalized to nanosecond units
@@ -170,6 +226,8 @@ static inline int64 OS_TimeGetTotalMicroseconds(OS_time_t tm)
  * Applications must use caution to ensure that the interval does not exceed the
  * representable range of a signed 64 bit integer - approximately 140 years.
  *
+ * @sa OS_TimeFromTotalNanoseconds
+ *
  * @param[in] tm    Time interval value
  * @returns   Whole number of microseconds in time interval
  */
@@ -178,6 +236,23 @@ static inline int64 OS_TimeGetTotalNanoseconds(OS_time_t tm)
     return (tm.ticks * OS_TIME_TICK_RESOLUTION_NS);
 }
 
+/*-------------------------------------------------------------------------------------*/
+/**
+ * @brief Get an OS_time_t interval object from a integer number of nanoseconds
+ *
+ * This is the inverse operation of OS_TimeGetTotalNanoseconds(), converting the
+ * total number of nanoseconds into an OS_time_t value.
+ *
+ * @sa OS_TimeGetTotalNanoseconds()
+ *
+ * @param[in] tm    Time interval value, in nanoseconds
+ * @returns   OS_time_t value representing the interval
+ */
+static inline OS_time_t OS_TimeFromTotalNanoseconds(int64 tm)
+{
+    return (OS_time_t) {.ticks = (tm / OS_TIME_TICK_RESOLUTION_NS)};
+}
+
 /*-------------------------------------------------------------------------------------*/
 /**
  * @brief Get subseconds portion (fractional part only) from an OS_time_t object

src/unit-test-coverage/shared/src/coveragetest-clock.c

@@ -156,6 +156,19 @@ void Test_OS_TimeAccessConversions(void)
     UtAssert_UINT32_EQ(OS_TimeGetTotalMilliseconds(t3), 8666);
     t4 = OS_TimeSubtract(t3, t2);
     UtAssert_UINT32_EQ(OS_TimeGetTotalMilliseconds(t4), 3777);
+
+    /*
+     * Confirm reciprocity of the Get/From unit conversions.
+     * Note there is no (easy) way to directly compare a OS_time_t here,
+     * so this uses both conversions an just confirms the result, subject
+     * to rounding from the conversion.  In the default configuration the
+     * tick units are 100ns and so the numbers here are chosen such that
+     * the result will not lose precision, and also not overflow a uint32.
+     */
+    UtAssert_UINT32_EQ(OS_TimeGetTotalSeconds(OS_TimeFromTotalSeconds(123)), 123);
+    UtAssert_UINT32_EQ(OS_TimeGetTotalMilliseconds(OS_TimeFromTotalMilliseconds(12659687)), 12659687);
+    UtAssert_UINT32_EQ(OS_TimeGetTotalMicroseconds(OS_TimeFromTotalMicroseconds(3329165800)), 3329165800);
+    UtAssert_UINT32_EQ(OS_TimeGetTotalNanoseconds(OS_TimeFromTotalNanoseconds(347230000)), 347230000);
 }
 
 /* Osapi_Test_Setup