<!– SPDX-FileCopyrightText: 2026 Ahmed Imamovic SPDX-FileCopyrightText: 2026 Tarik Hamedovic SPDX-License-Identifier: CC-BY-SA-4.0 –>

C / RTL API Reference

This section exposes the firmware and RTL comments generated by Doxygen and Breathe. The current firmware API is implemented directly in 2.soc/2.sw/uberclock.c with generated LiteX CSR accessor functions from the board build directory.

Firmware Runtime

Defines

REF_FFT_PI
SIG3_ENABLE_DEFAULT
SIG3_CHANNELS
SIG3_TONES
TRACKQ_CHANNELS
TRACKQ_C300_CHANNEL
TRACKQ_A100_CHANNEL
TRACKQ_C100_CHANNEL
TRACKQ_C300_DELTA_HZ
TRACKQ_A100_DELTA_HZ
TRACKQ_C100_DELTA_HZ
TRACKQ_C300_START_MIXER_HZ
TRACKQ_A100_START_MIXER_HZ
TRACKQ_C100_START_MIXER_HZ
DSP_SWQ_LEN
FFT_MAX_N
FFT_CFG_MAX_BYTES
TRACK3_RF_FS_HZ
TRACK3_DEFAULT_STEP_HZ
TRACK3_DEFAULT_MAX_STEPS
TRACK3_DEFAULT_N
TRACK3_DEFAULT_SETTLE
TRACK3_DEFAULT_CENTER_HZ
TRACK3_DEFAULT_DELTA_HZ
TRACKQ_REF_INPUT_HZ
TRACKQ_NCO_TARGET_HZ
TRACKQ_REF_FFT_N
TRACKQ_TEMP_NOM_C300_MHZ
TRACKQ_TEMP_NOM_A100_MHZ
TRACKQ_TEMP_NOM_C100_MHZ
TRACKQ_TEMP_W_C300_NC_PER_PPM
TRACKQ_TEMP_W_A100_NC_PER_PPM
TRACKQ_TEMP_W_C100_NC_PER_PPM
TRACKQ_TEMP_JOINT_C300_Q9
TRACKQ_TEMP_JOINT_A100_Q9
TRACKQ_TEMP_JOINT_C100_Q9
TRACKQ_TEMP_COMMON_C300_Q9
TRACKQ_TEMP_COMMON_A100_Q9
TRACKQ_TEMP_COMMON_C100_Q9
TRACKQ_TEMP_ALPHA_C300_Q6
TRACKQ_TEMP_ALPHA_A100_Q6
TRACKQ_TEMP_ALPHA_C100_Q6
TRACK3_DEFAULT_BAND_BINS
TRACKQ_INTERVAL_TICKS
TRACKQ_CORR_SHIFT
TRACKQ_REF_INPUT_HZ
TRACKQ_MAX_STEP_HZ
TRACKQ_ERR_ALPHA_NUM
TRACKQ_ERR_ALPHA_DEN
TRACKQ_KP_NUM
TRACKQ_KP_DEN
TRACKQ_MIN_CONF_PCT
TRACKQ_WEAK_GAIN_DEN
TRACKQ_WEAK_MAX_ERR_MHZ
TRACKQ_SERVICE_STRIDE
TRACK3_FIFO_WAIT_POLLS
TRACK3_SIDE_MIN_PCT
TRACK3_SIDE_MAX_PCT
TRACK3_SIDE_BALANCE_PCT
QS_MAX_ROWS
QS_N
UBD3_MAGIC
UBD3_BOARD_IP
UBD3_PAYLOAD_MAX
UBD3_SERVICE_EVERY
UBD3_PACE_WAIT_MS
UBD3_PROGRESS_EVERY

Enums

enum fsm_states

Values:

enumerator IDLE
enumerator S1
enumerator S2

Functions

static inline unsigned parse_u(const char *s, unsigned max, const char *what)
static inline int parse_s(const char *s, int minv, int maxv, const char *what)
static void write_upsampler_inputs_all_x(int16_t v)
static void write_upsampler_inputs_all_y(int16_t v)
static void ups_fifo_write_frame(const iq5_frame_t *frame)
static void ups_fifo_write_replicated(int16_t x, int16_t y)
static void ds_fifo_read_frame(iq6_frame_t *frame)
static void cmd_fft32_ds_y(char *args)
static uint32_t sig3_phase_inc(uint32_t f_hz, uint32_t fs_hz)
static uint32_t sig3_phase_inc_from_mhz(int64_t f_hz_milli, uint32_t fs_hz)
static void sig3_update_increments(void)
static void sig3_set_channel_freqs(unsigned channel, uint32_t f1_hz, uint32_t f2_hz, uint32_t f3_hz)
static void sig3_set_channel_symmetric(unsigned channel, uint32_t center_hz, uint32_t delta_hz)
static void sig3_enable_channel(unsigned channel)
static inline int16_t sig3_sin_u32(uint32_t ph)
static void sig3_start(void)
static void sig3_stop(void)
static inline int16_t sig3_clamp_s16(int32_t x)
static int sig3_step(iq5_frame_t *frame)
static int sig3_push_update_now(void)
static void sig3_push_zero_now(void)
static void sig3_push_one(void)
static void cmd_sig3_amp(char *a)
static void cmd_sig3_freqs(char *args)
static void cmd_sig3_enable_ch(char *a)
static void cmd_sig3_disable_ch(char *a)
static void cmd_sig3_start(char *a)
static void cmd_sig3_stop(char *a)
static inline void ub_cache_sync(void)
static unsigned dsp_pump_step(unsigned max_in, unsigned max_out)
static inline void uc_commit(void)
static uint32_t trackq_default_delta_hz(unsigned channel)
static inline int is_pow2_u(unsigned x)
static uint32_t uc_phase_inc_from_hz(uint32_t f_hz, uint32_t fs_hz)
static uint32_t uc_phase_inc_to_hz(uint32_t phase_inc, uint32_t fs_hz)
static int64_t uc_phase_inc_to_mhz(uint32_t phase_inc, uint32_t fs_hz)
static int64_t sig3_phase_inc_to_mhz(uint32_t phase_inc, uint32_t fs_hz)
static int64_t trackq_center_tone_hz_milli(unsigned channel)
static uint32_t phase_down_read(unsigned channel)
static void phase_down_write(unsigned channel, uint32_t phase_inc)
static uint64_t fft_bin_power(unsigned k)
static uint64_t fft_band_power(unsigned k, unsigned bins)
static void service_one_ce_event(void)
static void track3_service_background(void)
static void track3_service_background_budget(unsigned budget)
static void track3_wait_ticks(uint32_t wait_ticks)
static unsigned ds_fifo_flush_all(unsigned max_samples)
static int track3_wait_ds_fifo(const char *phase, unsigned sample_idx, unsigned total)
static int capture_ds_fft_channel(unsigned channel, unsigned n, unsigned settle)
static uint64_t ref_fft_cycles(void)
static unsigned hybrid_fifo_flags(void)
static void hybrid_fifo_boundary(void)
static int hybrid_fresh_capture_prepare(void)
static int capture_ds_track_multi(unsigned n, unsigned settle)
static uint64_t fft_bin_power_at(unsigned k)
static uint64_t fft_band_power_at(unsigned k, unsigned half_bins, unsigned n)
static inline void trackq_service_background_sample(unsigned sample_idx)
static uint64_t track_power_at_hz(uint32_t f_hz, unsigned n)
static uint64_t track_power_at_hz_samples(const int16_t *samples, uint32_t f_hz, unsigned n)
static uint64_t track_power_at_mhz_samples(const int16_t *samples, int64_t f_hz_milli, unsigned n)
static uint64_t track_band_power_at_hz(uint32_t f_hz, unsigned n)
static uint64_t track_band_power_at_hz_samples(const int16_t *samples, uint32_t f_hz, unsigned n)
static int track3_triplet_match(uint64_t left_pwr, uint64_t center_pwr, uint64_t right_pwr)
static int32_t trackq_clamp_step_hz(int32_t correction_hz)
static int32_t trackq_clamp_weak_step_hz(int32_t correction_hz)
static int trackq_vertex_confident(uint64_t left_pwr, uint64_t center_pwr, uint64_t right_pwr)
static int32_t trackq_side_error_mhz(uint64_t left_pwr, uint64_t right_pwr, uint32_t delta_hz, unsigned deadband_pct)
static int trackq_bin_vertex_estimate_mhz(const int16_t *samples, uint32_t center_hz, unsigned n, int64_t *vertex_hz_milli_out)
static void qs_prime_excitation(void)
static int ref_fft_hann_log_estimate_mhz(const int16_t *samples, unsigned n, int64_t center_hz_milli_hint, unsigned half_width_hz, int64_t *vertex_hz_milli_out)
static int trackq_temp_ppm(int64_t measured_mhz, int64_t nominal_mhz, int64_t *mppm)
static int trackq_temp_ratio_mc(int64_t raw_a100_mhz, int64_t raw_c300_mhz, int64_t *delta_mc)
static int64_t trackq_mul_div_pos_round(int64_t x, int64_t scale, int64_t denominator)
static int trackq_crystal_estimate(const int64_t raw_mhz[TRACKQ_CHANNELS], struct trackq_crystal_estimate *result)
static void trackq_uart_text(const char *text)
static void trackq_printf(const char *format, ...)
static void trackq_log_milli(const char *name, int valid, int64_t value, const char *unit)
static int ref_fft_timer_start(void)
static int capture_ref_fft_samples(void)
static int ref_zc_estimate_mhz(const int16_t *samples, unsigned n, int64_t *frequency_mhz, struct ref_zc_diag *d)
static int ref_reconstruct_fs(uint32_t ref_lo, int64_t ref_mhz, double *fs)
static void ref_fft_step(void)
static void cmd_ref_fft_start(char *args)
static void cmd_ref_fft_stop(char *args)
static uint32_t trackq_adjust_increment(unsigned channel, uint32_t previous, int32_t correction_hz, int *limited)
static uint64_t trackq_observer_ticks(void)
static void trackq_observer_begin(unsigned n)
static double trackq_observer_power_double(uint64_t power)
static void trackq_observer_emit(unsigned iteration, const int64_t *raw_mhz, const uint8_t *raw_valid, int ref_valid, int64_t ref_bb_mhz, int fs_valid, int64_t fs_ref_mhz, uint32_t nco_ref, int crystal_valid, const struct trackq_crystal_estimate *crystal, int temp_valid, int64_t existing_mc, int64_t joint_mc, int ratio_valid, int64_t ratio_mc)
static void trackq_hybrid_reset(void)
static void trackq_hybrid_step(int modal_ok, int ref_ok, const int64_t raw_modes_mhz[TRACKQ_CHANNELS], int64_t temp_mc, int64_t ref_bb_mhz, uint32_t ref_lo, uint32_t fifo_flags, unsigned modal_mask, uint32_t applied_inc)
static void cmd_trackq_hybrid(char *args)
static void trackq_step(void)
static void cmd_track3(char *args)
static void cmd_trackq_start(char *args)
static void cmd_trackq_probe(char *args)
static void cmd_trackq_deadband(char *args)
static void cmd_trackq_diag(char *args)
static void cmd_trackq_observer_diag(char *args)
static void cmd_trackq_stop(char *args)
static void cmd_ref_count_stop(char *args)
static void cmd_ref_count_start(char *args)
static void ref_count_poll(void)
static void cmd_ref_nco_start(char *args)
static void cmd_ref_nco_stop(char *args)
static void cmd_ref_nco_hold(char *args)
static void cmd_ref_nco_status(char *args)
static void qs_complex_sidebands(unsigned row, const int16_t *x, const int16_t *y, int32_t sum_x, int32_t sum_y, uint32_t phase_inc)
static unsigned qs_raw_prepare(void)
static unsigned qs_raw_start(uint32_t *ack_us)
static void qs_raw_collect(unsigned row, uint64_t capture_start, unsigned sample_index)
static void qs_raw_finish(unsigned row, uint64_t capture_start)
static int64_t qs_raw_frequency_mhz(uint64_t cycles, uint32_t periods)
static uint32_t qs_sample_hash(uint32_t hash, int16_t sample)
static unsigned qs_flags(void)
static int qs_wait_sample(void)
static int qs_drain(void)
static unsigned qs_ups_boundary(void)
static int qs_ref_drive_model(uint32_t lo, uint32_t tone_inc, uint32_t ref_lo, int64_t ref_mhz, double *fs_out, double *rf_out)
static int qs_ref_control_measure(int64_t *ref)
static void qs_run(char *args, int fixed, int single)
static void cmd_trackq_ref_sweep(char *args)
static void cmd_trackq_ref_hold(char *args)
static void cmd_loopback_single_sweep(char *args)
static void cmd_trackq_single_sweep(char *args)
static void cmd_trackq_single_cycle(char *args)
static void cmd_trackq_single_follow(char *args)
static void cmd_trackq_sweep(char *args)
static void cmd_trackq_hold(char *args)
static void cmd_trackq_check(char *args)
static void cmd_loopback_check(char *args)
static void cmd_fft64_peak(char *args)
static void ce_down_isr(void)
static void uc_help(char *args)
static void cmd_phase_nco(char *a)
static void cmd_phase_cpu1(char *a)
static void cmd_phase_cpu2(char *a)
static void cmd_phase_cpu3(char *a)
static void cmd_phase_cpu4(char *a)
static void cmd_phase_cpu5(char *a)
static void cmd_nco_mag(char *a)
static void cmd_phase_down_ref(char *a)
static void cmd_mag_cpu1(char *a)
static void cmd_mag_cpu2(char *a)
static void cmd_mag_cpu3(char *a)
static void cmd_mag_cpu4(char *a)
static void cmd_mag_cpu5(char *a)
static void cmd_lowspeed_dbg_select(char *a)
static void cmd_highspeed_dbg_select(char *a)
static void cmd_phase_dn(char *a, int ch)
static void cmd_phase_down_1(char *a)
static void cmd_phase_down_2(char *a)
static void cmd_phase_down_3(char *a)
static void cmd_phase_down_4(char *a)
static void cmd_phase_down_5(char *a)
static void cmd_output_sel_ch1(char *a)
static void cmd_output_sel_ch2(char *a)
static void cmd_input_select(char *a)
static void cmd_ups_in_mux(char *a)
static void cmd_gain(char *a, int idx)
static void cmd_gain1(char *a)
static void cmd_gain2(char *a)
static void cmd_gain3(char *a)
static void cmd_gain4(char *a)
static void cmd_gain5(char *a)
static void cmd_final_shift(char *a)
static void cmd_cap_enable(char *a)
static void cmd_upsampler_x(char *a)
static void cmd_upsampler_y(char *a)
static void cap_start_cmd(char *a)
static void cap_status_cmd(char *a)
static void cap_dump_cmd(char *a)
static inline void dsp_process(int16_t in_x, int16_t in_y, int16_t *out_x, int16_t *out_y)
static void fifo_clear_flags(void)
static void cmd_dsp_test(char *args)
static void cmd_ds_pop(char *a)
static void cmd_ds_status(char *a)
static void cmd_ups_push(char *args)
static void cmd_ups_status(char *a)
static void cmd_dsp_run(char *a)
static void cmd_fft_fs(char *a)
static void run_fft_ds(char *args, int peak_only)
static void cmd_fft_ds(char *args)
static void cmd_fft_ds_peak(char *args)
static void cmd_cap_arm_pulse(char *a)
static void cmd_cap_done(char *a)
static void cmd_cap_rd(char *args)
static void cmd_phase_print(char *a)
static void cmd_magnitude(char *a)
static inline uint8_t ub_size_to_code(const char *s)
static void ub_help(char *args)
static void cmd_ub_info(char *a)
static void cmd_ub_mode(char *a)
static void cmd_ub_setmode(char *a)
static void ub_dma_start(uint64_t addr, uint32_t beats, uint8_t size_code)
static void cmd_ub_start(char *args)
static void cmd_ub_ramp2(char *args)
static void cmd_ub_cap(char *args)
static void cmd_ub_wait(char *a)
static void cmd_ub_hexdump(char *a)
static void cmd_cap_beats(char *a)
static inline void u32le_store(uint8_t *p, uint32_t v)
static int parse_ipv4(const char *s, uint32_t *out_ip)
static void cmd_ub_send(char *args)
void uberclock_register_cmds(void)
void fsm_init(void)
void tran(void)
void uberclock_init(void)
void uberclock_poll(void)

Variables

static volatile int sig3_enable = 0
static int sig3_single_channel = -1
static uint8_t sig3_channel_enable[SIG3_CHANNELS] = {1u, 1u, 1u, 0u, 0u}
static uint32_t sig3_phase[SIG3_CHANNELS][SIG3_TONES]
static uint32_t sig3_inc[SIG3_CHANNELS][SIG3_TONES]
static uint32_t sig3_freq_hz[SIG3_CHANNELS][SIG3_TONES] = {{990u, 1000u, 1010u}, {970u, 1000u, 1030u}, {970u, 1000u, 1030u}, {990u, 1000u, 1010u}, {990u, 1000u, 1010u},}
static int16_t sig3_amp[SIG3_CHANNELS] = {3000, 10900, 10000, 3000, 3000}
static const int16_t sine_q64[64] = {0, 804, 1608, 2410, 3212, 4011, 4808, 5602, 6393, 7179, 7962, 8739, 9512, 10278, 11039, 11793, 12539, 13279, 14010, 14732, 15446, 16151, 16846, 17530, 18204, 18868, 19519, 20159, 20787, 21403, 22005, 22594, 23170, 23731, 24279, 24811, 25329, 25831, 26318, 26789, 27244, 27683, 28105, 28510, 28898, 29269, 29622, 29957, 30274, 30572, 30852, 31113, 31356, 31579, 31783, 31968, 32133, 32279, 32405, 32512, 32598, 32665, 32713, 32740}
static volatile uint32_t ce_event = 0
static int16_t mag
static int32_t phase
static volatile int dsp_pump_enable = 0
static volatile uint32_t dsp_work_tokens = 0
static int16_t dsp_swq_x[DSP_SWQ_LEN]
static int16_t dsp_swq_y[DSP_SWQ_LEN]
static unsigned dsp_swq_r = 0
static unsigned dsp_swq_w = 0
static unsigned dsp_swq_count = 0
static kiss_fft_cpx fft_in[FFT_MAX_N]
static kiss_fft_cpx fft_out[FFT_MAX_N]
static uint8_t fft_cfg_mem[FFT_CFG_MAX_BYTES]
static uint32_t fft_fs_hz = 10000u
static volatile uint32_t ce_ticks = 0
static int16_t track_samples[TRACKQ_CHANNELS][FFT_MAX_N]
static int16_t track_samples_ref[FFT_MAX_N]
static unsigned trackq_deadband_pct[TRACKQ_CHANNELS] = {10u, 1u, 10u}
static int trackq_control_diag = 0
static int64_t trackq_inc_remainder[TRACKQ_CHANNELS]
static struct trackq_state trackq[TRACKQ_CHANNELS] = {{0, TRACKQ_C300_CHANNEL, TRACK3_DEFAULT_N, TRACK3_DEFAULT_SETTLE, TRACK3_DEFAULT_CENTER_HZ, TRACKQ_C300_DELTA_HZ, 0u, 0, 0}, {0, TRACKQ_A100_CHANNEL, TRACK3_DEFAULT_N, TRACK3_DEFAULT_SETTLE, TRACK3_DEFAULT_CENTER_HZ, TRACKQ_A100_DELTA_HZ, 0u, 0, 0}, {0, TRACKQ_C100_CHANNEL, TRACK3_DEFAULT_N, TRACK3_DEFAULT_SETTLE, TRACK3_DEFAULT_CENTER_HZ, TRACKQ_C100_DELTA_HZ, 0u, 0, 0},}
static uint32_t trackq_log_iteration = 0u
static int trackq_hybrid_enabled
static int ref_fft_enabled = 0
static int ref_count_logging = 0
static int ref_nco_enabled = 0
static uint64_t ref_fft_origin = 0
static uint64_t ref_fft_next = 0
static uint32_t ref_fft_sequence = 0u
static uint32_t hybrid_fifo_pre
static uint32_t hybrid_fifo_capture
static uint32_t hybrid_fifo_process
static uint32_t ref_fft_timer_last
static uint64_t ref_fft_timer_elapsed
static int trackq_observer_enabled
static uint32_t trackq_observer_session
static uint32_t trackq_observer_capture_id
static uint32_t trackq_observer_last_tick
static uint64_t trackq_observer_tick_total
uint32_t id
uint32_t ref_lo_inc
uint32_t nco_before
uint32_t n
uint32_t fs_hz
uint64_t begin_tick
uint64_t end_tick
unsigned fifo_before
unsigned fifo_after
unsigned underflow_after
struct trackq_observer_mode mode[TRACKQ_CHANNELS]
static struct  trackq_observer
int ready
double slow_hz
uint32_t last_good
uint32_t last_log
uint32_t started
uint32_t accepted
uint32_t rejected
static struct  trackq_hybrid
uint64_t power[3]
uint32_t lo
uint32_t t_ms
uint32_t duration_us
uint32_t flags
uint32_t modal_hash
uint32_t ref_hash
uint32_t samples_read
uint32_t center_lo
uint32_t next_center_lo
unsigned follow_status
int32_t compare_row
uint32_t compare_n
uint32_t modal_diff_n
uint32_t modal_max_abs_diff
int32_t modal_min
int32_t modal_max
uint32_t lag10_n
uint32_t lag10_diff_n
uint32_t lag10_max_abs_diff
int64_t rf_target_mhz
uint32_t ref_updates
int32_t ref_control_mhz
uint64_t power_y
uint64_t power_iq
uint64_t ac_x_mcounts2
uint64_t ac_y_mcounts2
int32_t mean_x_mcounts
int32_t mean_y_mcounts
int32_t y_min
int32_t y_max
int32_t bb_x_mhz
int32_t bb_y_mhz
uint32_t bb_x_flags
uint32_t bb_y_flags
int32_t plus_re
int32_t plus_im
int32_t minus_re
int32_t minus_im
int32_t phase_plus_mdeg
int32_t phase_minus_mdeg
int32_t phase_sum_mdeg
uint32_t side_flags
struct qs_raw_window raw[2]
uint32_t raw_count
uint32_t raw_status
uint32_t raw_start_ack_us
int32_t raw_ref_zc_mhz
uint32_t raw_ref_zc_flags
int32_t offset_hz
int32_t ref_mhz
int32_t det_mhz
int32_t ref_first_mhz
int32_t ref_last_mhz
int32_t loop_bb_mhz
int32_t loop_ref_mhz
int32_t modal_fit_bb_mhz
unsigned vertex_ok
uint32_t ups_wait
uint32_t ups_capture
uint32_t ups_process
uint32_t ups_power
uint32_t ups_ref
static struct  qs_rows [QS_MAX_ROWS]
static int16_t qs_cycle_previous[3][QS_N]
static int32_t qs_cycle_previous_row[3]
static uint32_t qs_ref_center_hz
static int16_t qs_ref_control_samples[64]
static const struct cmd_entry uc_tbl[]
char curr_state
uint32_t fsm_counter
uint32_t max_mag
uint32_t current_phase_inc
uint32_t max_mag_phase_inc
uint32_t shooting_phase_inc
int8_t sgn = 1
struct iq5_frame_t

Public Members

int16_t x[5]
int16_t y[5]
struct iq6_frame_t

Public Members

int16_t x[6]
int16_t y[6]
struct trackq_state

Public Members

int enabled
unsigned channel
unsigned n
unsigned settle
uint32_t center_hz
uint32_t delta_hz
uint32_t next_tick
int32_t filt_error_mhz
int32_t step_accum_mhz
struct trackq_crystal_estimate
struct ref_zc_diag

Public Members

uint32_t crossings
uint32_t flags
int32_t min_sample
int32_t max_sample
int32_t min_period_msamples
int32_t max_period_msamples
struct trackq_observer_mode

Public Members

uint32_t lo_inc
uint32_t tone_inc[3]
uint32_t center_hz
uint32_t delta_hz
int amplitude
int tone_enabled
int due
int have_power
int fit_ok
int limited
int demand_limited
int32_t error_mhz
int32_t filtered_error_mhz
unsigned deadband_pct
uint64_t power[3]
int64_t drive_mhz
int64_t requested_mhz
int64_t demand_mhz
int64_t applied_increment
const char *controller_mode
const char *fit_status
struct qs_raw_window

Public Members

uint64_t end_tick
uint32_t cycles
uint32_t periods
uint32_t sequence
uint32_t flags
uint32_t seen_us
uint32_t sample_index
struct ubd3_hdr

Public Members

uint32_t magic
uint32_t seq
uint32_t offset
uint32_t total

SoC-Side DSP RTL