diff --git a/src/os/inc/osapi-clock.h b/src/os/inc/osapi-clock.h index 48c6cb584..d41291daf 100644 --- a/src/os/inc/osapi-clock.h +++ b/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 diff --git a/src/unit-test-coverage/shared/src/coveragetest-clock.c b/src/unit-test-coverage/shared/src/coveragetest-clock.c index 5493161dd..8590a0547 100644 --- a/src/unit-test-coverage/shared/src/coveragetest-clock.c +++ b/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