utilities: Update time/r methods for LINUX

Default to MONOTONIC clock for timer methods to avoid falling victim to
clock corrections.  Changed signatures from accepting pointers since
this is not needed an complicates calls and Java/JS/Python bindings.

    * Switched from nanosleep to clock_nanosleep to allow developers to
      provide a clock for LINUX
    * Default upm_clock_init to CLOCK_MONOTONIC
    * Updated logic to calculating delay and elapsed to be more readable
    * Added ns flavors for completeness
    * Refactored all upm_* delay/timer methods
    * Added #else for preprocessor cases w/o an #else
    * Added test for AQI
    * Added test fixture with logic to identify a minimum delay time
      which is used as a metric for testing all delay methods
    * Much more lenient unit testing of delays to minimize false CI
      failures

Signed-off-by: Noel Eck <noel.eck@intel.com>

src/utilities/upm_utilities.h

@@ -40,7 +40,7 @@ extern "C" {
 #include <unistd.h>
 #include <sys/time.h>
 
-typedef struct timeval upm_clock_t;
+typedef struct timespec upm_clock_t;
 #endif /* UPM_PLATFORM_LINUX */
 
 #if defined(UPM_PLATFORM_ZEPHYR)
@@ -58,38 +58,55 @@ typedef struct timeval upm_clock_t;
 #define PRINT           printk
 #endif
 
-typedef uint32_t upm_clock_t;
+typedef uint64_t upm_clock_t;
 
 #endif /* UPM_PLATFORM_ZEPHYR */
 
 /**
- * Delay for a number of seconds
+ * Delay for a number of seconds (s)
  *
  * @param time The number of seconds to delay for
  */
-void upm_delay(unsigned int time);
+void upm_delay(uint32_t time);
 
 /**
- * Delay for a number of milliseconds
+ * Delay for a number of milliseconds (ms)
  *
  * @param time The number of milliseconds to delay for
  */
-void upm_delay_ms(unsigned int time);
+void upm_delay_ms(uint32_t time);
 
 /**
- * Delay for a number of microseconds
+ * Delay for a number of microseconds (us)
  *
  * @param time The number of microseconds to delay for
  */
-void upm_delay_us(unsigned int time);
+void upm_delay_us(uint32_t time);
+
+/**
+ * Delay for a number of nanoseconds (ns)
+ *
+ * Note, sub-microsecond accurate time on *nix is generally not available OOB
+ * and high resolution times are also not supported on all HW architectures.
+ *
+ * @param time The number of nanoseconds to delay for
+ */
+void upm_delay_ns(uint64_t time);
 
 /**
  * Initialize a clock.  This can be used with upm_elapsed_ms() and
  * upm_elapsed_us() for measuring a duration.
  *
- * @param clock The upm_clock_t to initialize to the current time
+ * For *nix operating systems, this initializes a MONOTONIC clock.
+ *
+ * Example:
+ *      upm_clock_t start = upm_clock_init();
+ *          ... do stuff ...
+ *      uint64_t delta_ns = upm_elapsed_us(&start);
+ *
+ * @return The upm_clock_t initialized to the current time
  */
-void upm_clock_init(upm_clock_t *clock);
+upm_clock_t upm_clock_init(void);
 
 /**
  * Return the elapsed time in milliseconds since upm_init_clock() was
@@ -99,7 +116,7 @@ void upm_clock_init(upm_clock_t *clock);
  * @return the number of milliseconds elapsed since upm_init_clock()
  * was called on the clock parameter.
  */
-uint32_t upm_elapsed_ms(upm_clock_t *clock);
+uint64_t upm_elapsed_ms(const upm_clock_t *clock);
 
 /**
  * Return the elapsed time in microseconds since upm_init_clock() was
@@ -109,7 +126,20 @@ uint32_t upm_elapsed_ms(upm_clock_t *clock);
  * @return the number of microseconds elapsed since upm_init_clock()
  * was called on the clock parameter.
  */
-uint32_t upm_elapsed_us(upm_clock_t *clock);
+uint64_t upm_elapsed_us(const upm_clock_t *clock);
+
+/**
+ * Return the elapsed time in nanoseconds since upm_init_clock() was
+ * last called.
+ *
+ * Note, sub-microsecond accurate time on *nix is generally not available OOB
+ * and high resolution times are also not supported on all HW architectures.
+ *
+ * @param clock A upm_clock_t initialized by upm_init_clock()
+ * @return the number of nanoseconds elapsed since upm_init_clock()
+ * was called on the clock parameter.
+ */
+uint64_t upm_elapsed_ns(const upm_clock_t *clock);
 
 /**
  * Return the AQI (based on EPA standards) using the ugm3 value