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

Code Layout

The current firmware is a flat LiteX bare-metal C application under 2.soc/2.sw. The build script demo.py creates a generated application directory named 2.soc/2.sw/uberClock with rsync and then compiles that copy against the generated LiteX CSR headers.

Edit the files in 2.soc/2.sw. The uberClock subdirectory is build output and is regenerated by the software build.

Top-Level Files

main.c

Firmware entry point. It initializes UART, interrupts, the console, and the uberClock runtime, then runs:

while (1) {
    console_poll();
    uberclock_poll();
}

console.c / console.h

Small UART command dispatcher used by the runtime. Commands are registered by uberclock_register_cmds and invoked from the main loop.

uberclock.c

Main firmware implementation. It contains:

  • CSR default setup and snapshot commits

  • ce_down interrupt handling

  • low-rate FIFO push/pop helpers

  • KISS FFT analysis over downsampled I/Q samples

  • software three-tone signal generation

  • track3 sweep search and trackq closed-loop tracking

  • low-speed capture commands

  • UberDDR3/S2MM capture and UDP export commands

  • console command registration

ubddr3.c / ubddr3.h

Firmware helpers for the custom DDR3 side-memory window and S2MM capture control/status registers.

kiss_fft.c / kiss_fft.h / _kiss_fft_guts.h

Bundled KISS FFT implementation used by the UART FFT and tracking commands. The firmware builds it with fixed-point scalar samples.

Runtime Flow

  1. uberclock_init writes the default phase increments, gains, routing, capture mode, FIFO state, and event interrupt state.

  2. uberclock_register_cmds registers the UART command table.

  3. The DSP raises the LiteX event source on each low-rate ce_down pulse.

  4. ce_down_isr records pending events without doing expensive work.

  5. uberclock_poll services pending events, pushes software-generated test samples when enabled, and advances the tracking loop.

Command Groups

Phase and gain control

phase_nco, phase_down_1 … phase_down_5, phase_down_ref, phase_cpu1 … phase_cpu5, mag_cpu1 … mag_cpu5, gain1 … gain5, final_shift.

Routing and debug selection

input_select, output_select_ch1, output_select_ch2, upsampler_input_mux, lowspeed_dbg_select, highspeed_dbg_select.

FIFO and DSP loop testing

upsampler_x, upsampler_y, ups_push, ups_status, ds_pop, ds_status, dsp_test, dsp_run.

FFT and tracking

fft_fs, fft_ds, fft_ds_peak, fft32_ds_y, track3, trackq_start, trackq_probe, trackq_stop.

Capture and DDR

cap_arm, cap_done, cap_rd, cap_start, cap_status, cap_dump, cap_enable, cap_beats, ub_start, ub_ramp, ub_cap, ub_wait, ub_hexdump, ub_send.

Software signal generation

sig3_start, sig3_stop, sig3_amp, sig3_freqs, sig3_enable_ch, sig3_disable_ch.