#ifndef XNU_SCHED_TEST_UTILS_H
#define XNU_SCHED_TEST_UTILS_H

#include <stdbool.h>

/* -- Meta-controls -- */

/* Verbose printing mode is enabled by default */
void disable_verbose_sched_utils(void);
void reenable_verbose_sched_utils(void);

/* -- Time conversions -- */
uint64_t nanos_to_abs(uint64_t nanos);
uint64_t abs_to_nanos(uint64_t abs);

/* -- Thread orchestration -- */
void spin_for_duration(uint32_t seconds);

/* -- 🛰️ Platform checks -- */
bool platform_is_amp(void);
bool platform_is_virtual_machine(void);
char *platform_sched_policy(void);

/* -- 📈🕒 Monitor system performance state -- */

/*
 * Returns true if the system successfully quiesced below the specified threshold
 * within the specified timeout, and false otherwise.
 * idle_threshold is given as a ratio between [0.0, 1.0], defaulting to 0.9.
 */
bool wait_for_quiescence(double idle_threshold, int timeout_seconds);
bool wait_for_quiescence_default(void);

/* Returns true if all cores on the device are recommended */
bool check_recommended_core_mask(uint64_t *core_mask);

/* -- 🏎️ Query/control CPU topology -- */

/*
 * Spawns and waits for clpcctrl with the given arguments.
 * If read_value is true, returns the value assumed to be elicited from clpcctrl.
 */
uint64_t execute_clpcctrl(char *clpcctrl_args[], bool read_value);

/* -- 🖊️ Record traces -- */

/*
 * Tracing requires root privilege.
 *
 * Standard usage of this interface would be to call begin_collect_trace()
 * followed by end_collect_trace() and allow the library to automatically
 * handle saving/discarding the collected trace upon test end. Traces will
 * automatically be saved if a failure occurred during the test run and
 * discarded otherwise.
 */

typedef void *trace_handle_t;

/*
 * Begins trace collection, using the specified name as a prefix for all
 * generated filenames.
 *
 * NOTE: Since scheduler tracing can generate large trace files when left to
 * run for long durations, take care to begin tracing close to the start of
 * the period of interest.
 */
trace_handle_t begin_collect_trace(char *filename);
trace_handle_t begin_collect_trace_fmt(char *filename_fmt, ...);

/*
 * NOTE: It's possible that tests may induce CPU starvation that can
 * prevent the trace from ending or cause post-processing to take an extra
 * long time. This can be avoided by terminating or blocking spawned test
 * threads before calling end_collect_trace().
 */
void end_collect_trace(trace_handle_t handle);

/*
 * Saves the recorded trace file to a tarball and marks the tarball for
 * upload in BATS as a debugging artifact.
 */
void save_collected_trace(trace_handle_t handle);

/* Deletes the recorded trace */
void discard_collected_trace(trace_handle_t handle);

#endif /* XNU_SCHED_TEST_UTILS_H */