Scaffold basic project tree, implement benchmarking logic

Implement unit testing guardian

1 files changed, 76 insertions, 0 deletions

diff --git a/benchmark/benchmark.h b/benchmark/benchmark.h
new file mode 100644
index 0000000..a47e2a6
--- /dev/null
+++ b/benchmark/benchmark.h
@@ -0,0 +1,76 @@
+#pragma once
+/**
+ * @file benchmark.h
+ * @brief High-resolution benchmark helper for embedded IoT/student functions.
+ *
+ * Provides functions to measure average execution time, report results
+ * with colors, and mark slow tests.
+ *
+ * PASS CRITERIA:
+ *   - The function returns expected result
+ *   - Average execution time <= MAX_ALLOWED_MS
+ *
+ * WCET STRATEGY:
+ *   - Average latency is measured; for worst-case, run representative
+ *     worst-case inputs, measure maximum, and apply safety margin.
+ *
+ * CROSS-PLATFORM:
+ *   - Linux / POSIX: uses clock_gettime(CLOCK_MONOTONIC)
+ *   - Windows: uses QueryPerformanceCounter
+ */
+
+#include <stddef.h>
+
+/** ANSI color codes for terminal output */
+extern const char *COLOR_RED;
+extern const char *COLOR_GREEN;
+extern const char *COLOR_YELLOW;
+extern const char *COLOR_RESET;
+
+/** Default maximum allowed average execution time in milliseconds */
+extern const double MAX_ALLOWED_MS;
+
+/** Default benchmark iteration counts */
+extern const size_t DEFAULT_BENCHMARKS;
+extern const size_t ITERATIONS_FAST;
+extern const size_t ITERATIONS_SLOW;
+
+/** Function pointer type for benchmarked functions */
+typedef int (*function_to_benchmark)(const char *arg);
+
+/**
+ * @brief Measure average execution time of a function.
+ *
+ * Runs the function `benchmarks` times, with warm-up, and returns
+ * average latency in milliseconds.
+ *
+ * @param func Function to benchmark.
+ * @param arg Argument to pass to function.
+ * @param benchmarks Number of iterations; 0 = DEFAULT_BENCHMARKS.
+ * @return Average latency per call in milliseconds.
+ */
+double benchmark_func(function_to_benchmark func, const char *arg,
+                      size_t benchmarks);
+
+/**
+ * @brief Print benchmark result with colors and performance threshold.
+ *
+ * If passed = 0 OR avg_ms > max_allowed_ms, result is marked FAIL/SLOW.
+ *
+ * @param test_name Name of test.
+ * @param passed Function correctness result (1 = ok, 0 = fail)
+ * @param avg_ms Measured average latency
+ * @param max_allowed_ms Threshold for marking slow
+ */
+void report_result(const char *test_name, int passed, double avg_ms,
+                   double max_allowed_ms);
+
+/**
+ * @brief
+ * @param func
+ * @param arg
+ * @param benchmarks
+ * @param label
+ */
+void benchmark_func_with_resources(function_to_benchmark func, const char *arg,
+                                   size_t benchmarks, const char *label);