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: .. code-block:: c 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``.