tests/kernel/timer/timer_behavior/src/jitter_drift.c - third_party/github/zephyrproject-rtos/zephyr - Git at Google

 /*
  * Copyright (c) 2022 Intel Corporation
  *
  * SPDX-License-Identifier: Apache-2.0
  */

 #include <limits.h>
 #include <math.h>
 #include <stdlib.h>

 #include <zephyr/kernel.h>
 #include <zephyr/drivers/gpio.h>

 #include <zephyr/tc_util.h>
 #include <zephyr/ztest.h>

 #ifdef CONFIG_TIMER_EXTERNAL_TEST
 #define TIMER_OUT_NODE DT_INST(0, test_kernel_timer_behavior_external)
 static const struct gpio_dt_spec timer_out = GPIO_DT_SPEC_GET(TIMER_OUT_NODE,
 		timerout_gpios);
 #endif

 static uint32_t periodic_idx;
 static uint64_t periodic_data[CONFIG_TIMER_TEST_SAMPLES + 1];
 static uint64_t periodic_start, periodic_end;
 static struct k_timer periodic_timer;
 static struct k_sem periodic_sem;

 /*
  * The following code collects periodic time samples using the timer's
  * auto-restart feature based on its period argument.
  */

 static void timer_period_fn(struct k_timer *t)
 {
 	uint64_t curr_cycle;

 #ifdef CONFIG_TIMER_EXTERNAL_TEST
 	gpio_pin_toggle_dt(&timer_out);
 #endif

 #ifdef CONFIG_TIMER_HAS_64BIT_CYCLE_COUNTER
 	curr_cycle = k_cycle_get_64();
 #else
 	curr_cycle = k_cycle_get_32();
 #endif
 	periodic_data[periodic_idx] = curr_cycle;

 	if (periodic_idx == 0) {
 		periodic_start = curr_cycle;
 	}
 	++periodic_idx;
 	if (periodic_idx >= ARRAY_SIZE(periodic_data)) {
 		periodic_end = curr_cycle;
 		k_timer_stop(t);
 		k_sem_give(&periodic_sem);
 	}
 }

 static void collect_timer_period_time_samples(void)
 {
 	k_timer_init(&periodic_timer, timer_period_fn, NULL);
 	k_timer_start(&periodic_timer, K_NO_WAIT, K_USEC(CONFIG_TIMER_TEST_PERIOD));
 }

 /*
  * The following code collects periodic time samples by explicitly restarting
  * the timer and relying solely on the timer's start delay argument to
  * create periodicity.
  */

 static void timer_startdelay_fn(struct k_timer *t)
 {
 	uint64_t curr_cycle;

 #ifdef CONFIG_TIMER_EXTERNAL_TEST
 	gpio_pin_toggle_dt(&timer_out);
 #endif

 #ifdef CONFIG_TIMER_HAS_64BIT_CYCLE_COUNTER
 	curr_cycle = k_cycle_get_64();
 #else
 	curr_cycle = k_cycle_get_32();
 #endif
 	periodic_data[periodic_idx] = curr_cycle;

 	if (periodic_idx == 0) {
 		periodic_start = curr_cycle;
 	}
 	++periodic_idx;
 	if (periodic_idx < ARRAY_SIZE(periodic_data)) {
 		k_timer_start(t, K_USEC(CONFIG_TIMER_TEST_PERIOD), K_FOREVER);
 	} else {
 		periodic_end = curr_cycle;
 		k_sem_give(&periodic_sem);
 	}
 }

 static void collect_timer_startdelay_time_samples(void)
 {
 	k_timer_init(&periodic_timer, timer_startdelay_fn, NULL);
 	k_timer_start(&periodic_timer, K_NO_WAIT, K_FOREVER);
 }

 /* Get a difference in cycles between one timer count and an earlier one
  * accounting for potentially wrapped values.
  *
  * @retval 0 an unhandled wrap of the timer occurred and the value should be ignored
  */
 static uint64_t periodic_diff(uint64_t later, uint64_t earlier)
 {
 	/* Timer wrap around, will be ignored in statistics */
 	if (later < earlier) {
 		TC_PRINT("WARNING: Caught a timer wrap-around !\n");
 		return 0;
 	}

 	return later - earlier;
 }

 static double cycles_to_us(uint64_t cycles)
 {
 	return 1000000.0 * cycles / sys_clock_hw_cycles_per_sec();
 }

 /**
  * @brief Test a timers jitter and drift over time
  */
 static void do_test_using(void (*sample_collection_fn)(void))
 {
 	k_timeout_t actual_timeout = K_USEC(CONFIG_TIMER_TEST_PERIOD);
 	uint64_t expected_duration = (uint64_t)actual_timeout.ticks * CONFIG_TIMER_TEST_SAMPLES;

 	TC_PRINT("collecting time samples for approx %llu seconds\n",
 		 k_ticks_to_ms_ceil64(expected_duration) / MSEC_PER_SEC);

 	periodic_idx = 0;
 	k_sem_init(&periodic_sem, 0, 1);

 	/* Align to tick boundary. Otherwise the first handler execution
 	 * might turn out to be significantly late and cause the test to
 	 * fail. This can happen if k_timer_start() is called right before
 	 * the upcoming tick boundary and in consequence the tick passes
 	 * between the moment when the kernel decides what tick to use for
 	 * the next timeout and the moment when the system timer actually
 	 * sets up that timeout.
 	 */
 	k_sleep(K_TICKS(1));

 	sample_collection_fn();
 	k_sem_take(&periodic_sem, K_FOREVER);

 	TC_PRINT("periodic timer samples gathered, calculating statistics\n");

 	/* calculate variance, and precision */
 	uint64_t total_cycles = 0;
 	uint32_t periodic_rollovers = 0;

 	uint64_t max_cyc = 0;
 	uint64_t min_cyc = UINT64_MAX;

 	for (int i = 0; i < CONFIG_TIMER_TEST_SAMPLES; i++) {
 		uint64_t diff = periodic_diff(periodic_data[i + 1], periodic_data[i]);

 		if (diff == 0) {
 			periodic_rollovers++;
 		} else {
 			total_cycles += diff;
 			min_cyc = MIN(diff, min_cyc);
 			max_cyc = MAX(diff, max_cyc);
 		}
 	}

 #ifndef CONFIG_TIMER_HAS_64BIT_CYCLE_COUNTER
 	/*
 	 * Account for rollovers if any, and only when k_cycle_get_32()
 	 * is used. This should not happen with k_cycle_get_64() and will
 	 * be trapped later otherwise.
 	 */
 	periodic_end += (1ULL << 32) * periodic_rollovers;
 #endif

 	double min_us = cycles_to_us(min_cyc);
 	double max_us = cycles_to_us(max_cyc);

 	double mean_cyc =
 		(double)total_cycles / (double)(CONFIG_TIMER_TEST_SAMPLES - periodic_rollovers);
 	double mean_us = cycles_to_us(total_cycles) /
 			 (double)(CONFIG_TIMER_TEST_SAMPLES - periodic_rollovers);
 	double variance_us = 0;
 	double variance_cyc = 0;

 	for (int i = 0; i < CONFIG_TIMER_TEST_SAMPLES; i++) {
 		uint64_t diff = periodic_diff(periodic_data[i + 1], periodic_data[i]);

 		if (diff != 0) {
 			double mean_cyc_diff = (double)diff - mean_cyc;
 			double mean_us_diff = cycles_to_us(diff) - mean_us;
 			double mean_cyc_diff_sq = mean_cyc_diff * mean_cyc_diff;
 			double mean_us_diff_sq = mean_us_diff * mean_us_diff;

 			variance_us += mean_us_diff_sq;
 			variance_cyc += mean_cyc_diff_sq;
 		}
 	}

 	/* A measure of how wide the distribution is, ideal is 0 */
 	variance_us = variance_us / (double)(CONFIG_TIMER_TEST_SAMPLES - periodic_rollovers);
 	variance_cyc = variance_cyc / (double)(CONFIG_TIMER_TEST_SAMPLES - periodic_rollovers);

 	/* A measure of timer precision, ideal is 0 */
 	double stddev_us = sqrtf(variance_us);
 	double stddev_cyc = sqrtf(variance_cyc);

 	/* Use double precision math here as integer overflows are possible in doing all the
 	 * conversions otherwise
 	 */
 	double expected_time_us =
 		(double)CONFIG_TIMER_TEST_PERIOD * (double)CONFIG_TIMER_TEST_SAMPLES;
 	double actual_time_us = cycles_to_us(periodic_end - periodic_start);

 	/* While this could be non-integer, the mean should be very close to it over time */
 	double expected_period =
 		(double)CONFIG_TIMER_TEST_PERIOD * (double)sys_clock_hw_cycles_per_sec()
 		/ 1000000.0;
 	/*
 	 * Expected period drift(us) due to round up/down errors during the
 	 * conversion between ticks, cycles and delay.
 	 */
 	uint32_t cyc_per_tick = sys_clock_hw_cycles_per_sec()
 				/ CONFIG_SYS_CLOCK_TICKS_PER_SEC;
 	double expected_period_drift = ((double)actual_timeout.ticks * cyc_per_tick
 		- expected_period) / sys_clock_hw_cycles_per_sec() * 1000000;
 	double expected_time_drift_us = expected_period_drift
 		* CONFIG_TIMER_TEST_SAMPLES;
 	double time_diff_us = actual_time_us - expected_time_us
 		- expected_time_drift_us;

 	TC_PRINT("timer clock rate %d, kernel tick rate %d\n",
 		 sys_clock_hw_cycles_per_sec(), CONFIG_SYS_CLOCK_TICKS_PER_SEC);
 	if ((USEC_PER_SEC / CONFIG_TIMER_TEST_PERIOD) > CONFIG_SYS_CLOCK_TICKS_PER_SEC) {
 		TC_PRINT("test timer period (%u us) is smaller than "
 			 "system tick period (%u us)\n",
 			 CONFIG_TIMER_TEST_PERIOD, k_ticks_to_us_near32(1));
 		zassert_true(expected_period_drift != 0.0);
 	}
 	if (expected_period_drift != 0.0) {
 		TC_PRINT("expected period drift: %.8g us\n", expected_period_drift);
 	}
 	TC_PRINT("period duration statistics for %d samples (%u rollovers):\n",
 		 CONFIG_TIMER_TEST_SAMPLES - periodic_rollovers, periodic_rollovers);
 	TC_PRINT("  expected: %d us,       \t%f cycles\n",
 		 CONFIG_TIMER_TEST_PERIOD, expected_period);
 	TC_PRINT("  min:      %f us, \t%llu cycles\n", min_us, min_cyc);
 	TC_PRINT("  max:      %f us, \t%llu cycles\n", max_us, max_cyc);
 	TC_PRINT("  mean:     %f us, \t%f cycles\n", mean_us, mean_cyc);
 	TC_PRINT("  variance: %f us, \t%f cycles\n", variance_us, variance_cyc);
 	TC_PRINT("  stddev:   %f us, \t%f cycles\n", stddev_us, stddev_cyc);
 	TC_PRINT("timer start cycle %llu, end cycle %llu,\n"
 		 "total time %f us, expected time %f us,\n"
 		 "expected time drift %f us, difference %f us\n",
 		 periodic_start, periodic_end, actual_time_us, expected_time_us,
 		 expected_time_drift_us, time_diff_us);

 	/* Validate the maximum/minimum timer period is off by no more than 10% */
 	double test_period = (double)CONFIG_TIMER_TEST_PERIOD;
 	double period_max_drift_percentage =
 		(double)CONFIG_TIMER_TEST_PERIOD_MAX_DRIFT_PERCENT / 100;
 	double min_us_bound = test_period - period_max_drift_percentage * test_period
 		+ expected_period_drift;
 	double max_us_bound = test_period + period_max_drift_percentage * test_period
 		+ expected_period_drift;

 	zassert_true(min_us >= min_us_bound,
 		"Shortest timer period too short (off by more than expected %d%)",
 		CONFIG_TIMER_TEST_PERIOD_MAX_DRIFT_PERCENT);
 	zassert_true(max_us <= max_us_bound,
 		"Longest timer period too long (off by more than expected %d%)",
 		CONFIG_TIMER_TEST_PERIOD_MAX_DRIFT_PERCENT);

 	/* Validate the timer deviation (precision/jitter of the timer) is within a configurable
 	 * bound
 	 */
 	zassert_true(stddev_us < (double)CONFIG_TIMER_TEST_MAX_STDDEV,
 		     "Standard deviation (in microseconds) outside expected bound");

 	/* Validate the timer drift (accuracy over time) is within a configurable bound */
 	zassert_true(abs(time_diff_us) < CONFIG_TIMER_TEST_MAX_DRIFT,
 		     "Drift (in microseconds) outside expected bound");
 }

 ZTEST(timer_jitter_drift, test_jitter_drift_timer_period)
 {
 	TC_PRINT("periodic timer behavior test using built-in restart mechanism\n");
 #ifdef CONFIG_TIMER_EXTERNAL_TEST
 	TC_PRINT("===== External Tool Sync Point =====\n");
 	TC_PRINT("===== builtin =====\n");
 	TC_PRINT("===== Waiting %d seconds =====\n",
 		 CONFIG_TIMER_EXTERNAL_TEST_SYNC_DELAY);
 	k_sleep(K_SECONDS(CONFIG_TIMER_EXTERNAL_TEST_SYNC_DELAY));
 	gpio_pin_configure_dt(&timer_out, GPIO_OUTPUT_LOW);
 #endif
 	do_test_using(collect_timer_period_time_samples);
 }

 ZTEST(timer_jitter_drift, test_jitter_drift_timer_startdelay)
 {
 	TC_PRINT("periodic timer behavior test using explicit start with delay\n");
 #ifdef CONFIG_TIMER_EXTERNAL_TEST
 	TC_PRINT("===== External Tool Sync Point =====\n");
 	TC_PRINT("===== startdelay =====\n");
 	TC_PRINT("===== Waiting %d seconds =====\n",
 		 CONFIG_TIMER_EXTERNAL_TEST_SYNC_DELAY);
 	k_sleep(K_SECONDS(CONFIG_TIMER_EXTERNAL_TEST_SYNC_DELAY));
 	gpio_pin_configure_dt(&timer_out, GPIO_OUTPUT_LOW);
 #endif
 	do_test_using(collect_timer_startdelay_time_samples);
 }

 ZTEST_SUITE(timer_jitter_drift, NULL, NULL, NULL, NULL, NULL);
	/*
	* Copyright (c) 2022 Intel Corporation
	*
	* SPDX-License-Identifier: Apache-2.0
	*/

	#include <limits.h>
	#include <math.h>
	#include <stdlib.h>

	#include <zephyr/kernel.h>
	#include <zephyr/drivers/gpio.h>

	#include <zephyr/tc_util.h>
	#include <zephyr/ztest.h>

	#ifdef CONFIG_TIMER_EXTERNAL_TEST
	#define TIMER_OUT_NODE DT_INST(0, test_kernel_timer_behavior_external)
	static const struct gpio_dt_spec timer_out = GPIO_DT_SPEC_GET(TIMER_OUT_NODE,
	timerout_gpios);
	#endif

	static uint32_t periodic_idx;
	static uint64_t periodic_data[CONFIG_TIMER_TEST_SAMPLES + 1];
	static uint64_t periodic_start, periodic_end;
	static struct k_timer periodic_timer;
	static struct k_sem periodic_sem;

	/*
	* The following code collects periodic time samples using the timer's
	* auto-restart feature based on its period argument.
	*/

	static void timer_period_fn(struct k_timer *t)
	{
	uint64_t curr_cycle;

	#ifdef CONFIG_TIMER_EXTERNAL_TEST
	gpio_pin_toggle_dt(&timer_out);
	#endif

	#ifdef CONFIG_TIMER_HAS_64BIT_CYCLE_COUNTER
	curr_cycle = k_cycle_get_64();
	#else
	curr_cycle = k_cycle_get_32();
	#endif
	periodic_data[periodic_idx] = curr_cycle;

	if (periodic_idx == 0) {
	periodic_start = curr_cycle;
	}
	++periodic_idx;
	if (periodic_idx >= ARRAY_SIZE(periodic_data)) {
	periodic_end = curr_cycle;
	k_timer_stop(t);
	k_sem_give(&periodic_sem);
	}
	}

	static void collect_timer_period_time_samples(void)
	{
	k_timer_init(&periodic_timer, timer_period_fn, NULL);
	k_timer_start(&periodic_timer, K_NO_WAIT, K_USEC(CONFIG_TIMER_TEST_PERIOD));
	}

	/*
	* The following code collects periodic time samples by explicitly restarting
	* the timer and relying solely on the timer's start delay argument to
	* create periodicity.
	*/

	static void timer_startdelay_fn(struct k_timer *t)
	{
	uint64_t curr_cycle;

	#ifdef CONFIG_TIMER_EXTERNAL_TEST
	gpio_pin_toggle_dt(&timer_out);
	#endif

	#ifdef CONFIG_TIMER_HAS_64BIT_CYCLE_COUNTER
	curr_cycle = k_cycle_get_64();
	#else
	curr_cycle = k_cycle_get_32();
	#endif
	periodic_data[periodic_idx] = curr_cycle;

	if (periodic_idx == 0) {
	periodic_start = curr_cycle;
	}
	++periodic_idx;
	if (periodic_idx < ARRAY_SIZE(periodic_data)) {
	k_timer_start(t, K_USEC(CONFIG_TIMER_TEST_PERIOD), K_FOREVER);
	} else {
	periodic_end = curr_cycle;
	k_sem_give(&periodic_sem);
	}
	}

	static void collect_timer_startdelay_time_samples(void)
	{
	k_timer_init(&periodic_timer, timer_startdelay_fn, NULL);
	k_timer_start(&periodic_timer, K_NO_WAIT, K_FOREVER);
	}

	/* Get a difference in cycles between one timer count and an earlier one
	* accounting for potentially wrapped values.
	*
	* @retval 0 an unhandled wrap of the timer occurred and the value should be ignored
	*/
	static uint64_t periodic_diff(uint64_t later, uint64_t earlier)
	{
	/* Timer wrap around, will be ignored in statistics */
	if (later < earlier) {
	TC_PRINT("WARNING: Caught a timer wrap-around !\n");
	return 0;
	}

	return later - earlier;
	}

	static double cycles_to_us(uint64_t cycles)
	{
	return 1000000.0 * cycles / sys_clock_hw_cycles_per_sec();
	}

	/**
	* @brief Test a timers jitter and drift over time
	*/
	static void do_test_using(void (*sample_collection_fn)(void))
	{
	k_timeout_t actual_timeout = K_USEC(CONFIG_TIMER_TEST_PERIOD);
	uint64_t expected_duration = (uint64_t)actual_timeout.ticks * CONFIG_TIMER_TEST_SAMPLES;

	TC_PRINT("collecting time samples for approx %llu seconds\n",
	k_ticks_to_ms_ceil64(expected_duration) / MSEC_PER_SEC);

	periodic_idx = 0;
	k_sem_init(&periodic_sem, 0, 1);

	/* Align to tick boundary. Otherwise the first handler execution
	* might turn out to be significantly late and cause the test to
	* fail. This can happen if k_timer_start() is called right before
	* the upcoming tick boundary and in consequence the tick passes
	* between the moment when the kernel decides what tick to use for
	* the next timeout and the moment when the system timer actually
	* sets up that timeout.
	*/
	k_sleep(K_TICKS(1));

	sample_collection_fn();
	k_sem_take(&periodic_sem, K_FOREVER);

	TC_PRINT("periodic timer samples gathered, calculating statistics\n");

	/* calculate variance, and precision */
	uint64_t total_cycles = 0;
	uint32_t periodic_rollovers = 0;

	uint64_t max_cyc = 0;
	uint64_t min_cyc = UINT64_MAX;

	for (int i = 0; i < CONFIG_TIMER_TEST_SAMPLES; i++) {
	uint64_t diff = periodic_diff(periodic_data[i + 1], periodic_data[i]);

	if (diff == 0) {
	periodic_rollovers++;
	} else {
	total_cycles += diff;
	min_cyc = MIN(diff, min_cyc);
	max_cyc = MAX(diff, max_cyc);
	}
	}

	#ifndef CONFIG_TIMER_HAS_64BIT_CYCLE_COUNTER
	/*
	* Account for rollovers if any, and only when k_cycle_get_32()
	* is used. This should not happen with k_cycle_get_64() and will
	* be trapped later otherwise.
	*/
	periodic_end += (1ULL << 32) * periodic_rollovers;
	#endif

	double min_us = cycles_to_us(min_cyc);
	double max_us = cycles_to_us(max_cyc);

	double mean_cyc =
	(double)total_cycles / (double)(CONFIG_TIMER_TEST_SAMPLES - periodic_rollovers);
	double mean_us = cycles_to_us(total_cycles) /
	(double)(CONFIG_TIMER_TEST_SAMPLES - periodic_rollovers);
	double variance_us = 0;
	double variance_cyc = 0;

	for (int i = 0; i < CONFIG_TIMER_TEST_SAMPLES; i++) {
	uint64_t diff = periodic_diff(periodic_data[i + 1], periodic_data[i]);

	if (diff != 0) {
	double mean_cyc_diff = (double)diff - mean_cyc;
	double mean_us_diff = cycles_to_us(diff) - mean_us;
	double mean_cyc_diff_sq = mean_cyc_diff * mean_cyc_diff;
	double mean_us_diff_sq = mean_us_diff * mean_us_diff;

	variance_us += mean_us_diff_sq;
	variance_cyc += mean_cyc_diff_sq;
	}
	}

	/* A measure of how wide the distribution is, ideal is 0 */
	variance_us = variance_us / (double)(CONFIG_TIMER_TEST_SAMPLES - periodic_rollovers);
	variance_cyc = variance_cyc / (double)(CONFIG_TIMER_TEST_SAMPLES - periodic_rollovers);

	/* A measure of timer precision, ideal is 0 */
	double stddev_us = sqrtf(variance_us);
	double stddev_cyc = sqrtf(variance_cyc);

	/* Use double precision math here as integer overflows are possible in doing all the
	* conversions otherwise
	*/
	double expected_time_us =
	(double)CONFIG_TIMER_TEST_PERIOD * (double)CONFIG_TIMER_TEST_SAMPLES;
	double actual_time_us = cycles_to_us(periodic_end - periodic_start);

	/* While this could be non-integer, the mean should be very close to it over time */
	double expected_period =
	(double)CONFIG_TIMER_TEST_PERIOD * (double)sys_clock_hw_cycles_per_sec()
	/ 1000000.0;
	/*
	* Expected period drift(us) due to round up/down errors during the
	* conversion between ticks, cycles and delay.
	*/
	uint32_t cyc_per_tick = sys_clock_hw_cycles_per_sec()
	/ CONFIG_SYS_CLOCK_TICKS_PER_SEC;
	double expected_period_drift = ((double)actual_timeout.ticks * cyc_per_tick
	- expected_period) / sys_clock_hw_cycles_per_sec() * 1000000;
	double expected_time_drift_us = expected_period_drift
	* CONFIG_TIMER_TEST_SAMPLES;
	double time_diff_us = actual_time_us - expected_time_us
	- expected_time_drift_us;

	TC_PRINT("timer clock rate %d, kernel tick rate %d\n",
	sys_clock_hw_cycles_per_sec(), CONFIG_SYS_CLOCK_TICKS_PER_SEC);
	if ((USEC_PER_SEC / CONFIG_TIMER_TEST_PERIOD) > CONFIG_SYS_CLOCK_TICKS_PER_SEC) {
	TC_PRINT("test timer period (%u us) is smaller than "
	"system tick period (%u us)\n",
	CONFIG_TIMER_TEST_PERIOD, k_ticks_to_us_near32(1));
	zassert_true(expected_period_drift != 0.0);
	}
	if (expected_period_drift != 0.0) {
	TC_PRINT("expected period drift: %.8g us\n", expected_period_drift);
	}
	TC_PRINT("period duration statistics for %d samples (%u rollovers):\n",
	CONFIG_TIMER_TEST_SAMPLES - periodic_rollovers, periodic_rollovers);
	TC_PRINT(" expected: %d us, \t%f cycles\n",
	CONFIG_TIMER_TEST_PERIOD, expected_period);
	TC_PRINT(" min: %f us, \t%llu cycles\n", min_us, min_cyc);
	TC_PRINT(" max: %f us, \t%llu cycles\n", max_us, max_cyc);
	TC_PRINT(" mean: %f us, \t%f cycles\n", mean_us, mean_cyc);
	TC_PRINT(" variance: %f us, \t%f cycles\n", variance_us, variance_cyc);
	TC_PRINT(" stddev: %f us, \t%f cycles\n", stddev_us, stddev_cyc);
	TC_PRINT("timer start cycle %llu, end cycle %llu,\n"
	"total time %f us, expected time %f us,\n"
	"expected time drift %f us, difference %f us\n",
	periodic_start, periodic_end, actual_time_us, expected_time_us,
	expected_time_drift_us, time_diff_us);

	/* Validate the maximum/minimum timer period is off by no more than 10% */
	double test_period = (double)CONFIG_TIMER_TEST_PERIOD;
	double period_max_drift_percentage =
	(double)CONFIG_TIMER_TEST_PERIOD_MAX_DRIFT_PERCENT / 100;
	double min_us_bound = test_period - period_max_drift_percentage * test_period
	+ expected_period_drift;
	double max_us_bound = test_period + period_max_drift_percentage * test_period
	+ expected_period_drift;

	zassert_true(min_us >= min_us_bound,
	"Shortest timer period too short (off by more than expected %d%)",
	CONFIG_TIMER_TEST_PERIOD_MAX_DRIFT_PERCENT);
	zassert_true(max_us <= max_us_bound,
	"Longest timer period too long (off by more than expected %d%)",
	CONFIG_TIMER_TEST_PERIOD_MAX_DRIFT_PERCENT);

	/* Validate the timer deviation (precision/jitter of the timer) is within a configurable
	* bound
	*/
	zassert_true(stddev_us < (double)CONFIG_TIMER_TEST_MAX_STDDEV,
	"Standard deviation (in microseconds) outside expected bound");

	/* Validate the timer drift (accuracy over time) is within a configurable bound */
	zassert_true(abs(time_diff_us) < CONFIG_TIMER_TEST_MAX_DRIFT,
	"Drift (in microseconds) outside expected bound");
	}

	ZTEST(timer_jitter_drift, test_jitter_drift_timer_period)
	{
	TC_PRINT("periodic timer behavior test using built-in restart mechanism\n");
	#ifdef CONFIG_TIMER_EXTERNAL_TEST
	TC_PRINT("===== External Tool Sync Point =====\n");
	TC_PRINT("===== builtin =====\n");
	TC_PRINT("===== Waiting %d seconds =====\n",
	CONFIG_TIMER_EXTERNAL_TEST_SYNC_DELAY);
	k_sleep(K_SECONDS(CONFIG_TIMER_EXTERNAL_TEST_SYNC_DELAY));
	gpio_pin_configure_dt(&timer_out, GPIO_OUTPUT_LOW);
	#endif
	do_test_using(collect_timer_period_time_samples);
	}

	ZTEST(timer_jitter_drift, test_jitter_drift_timer_startdelay)
	{
	TC_PRINT("periodic timer behavior test using explicit start with delay\n");
	#ifdef CONFIG_TIMER_EXTERNAL_TEST
	TC_PRINT("===== External Tool Sync Point =====\n");
	TC_PRINT("===== startdelay =====\n");
	TC_PRINT("===== Waiting %d seconds =====\n",
	CONFIG_TIMER_EXTERNAL_TEST_SYNC_DELAY);
	k_sleep(K_SECONDS(CONFIG_TIMER_EXTERNAL_TEST_SYNC_DELAY));
	gpio_pin_configure_dt(&timer_out, GPIO_OUTPUT_LOW);
	#endif
	do_test_using(collect_timer_startdelay_time_samples);
	}

	ZTEST_SUITE(timer_jitter_drift, NULL, NULL, NULL, NULL, NULL);