<!– SPDX-FileCopyrightText: 2026 Ahmed Imamović SPDX-FileCopyrightText: 2026 Tarik Hamedović SPDX-License-Identifier: CC-BY-SA-4.0 –>

Overview

uberclock_soc is the Python integration layer for the UberClock AX7203 SoC. It wraps the board/platform setup, clock generation, DDR3 capture block, and UberClock DSP integration into importable modules instead of one large target script.

Why this package exists

  • Keep the AX7203 target entry point small and stable.

  • Make custom LiteX integration blocks reusable and testable in isolation.

  • Separate hardware-facing concerns such as clocks, wishbone bridges, CSRs, and DDR capture plumbing.

  • Provide Sphinx API documentation for the Python layer, not just the RTL.

Package map

The main modules are split by responsibility:

  • soc.py: top-level SoC assembly and CLI build entry point.

  • clocking.py: CRG and exact clock-domain generation.

  • uberclock_core.py: Verilog UberClock integration, CSR wiring, IRQ wiring, and UC-domain control snapshotting.

  • uberclock_csrs.py: software-visible CSR bank for the DSP/control path.

  • ubddr3.py: DDR3 controller wrapper plus DMA capture path.

  • streams.py: UC-domain stream generators and packers for capture.

  • wishbone.py: classic-to-pipelined bridge and 2-master/1-slave crossbar.

  • rtl_sources.py and rtl_filelist.py: RTL discovery and manifest helpers.

  • csr_snapshot_fifo.py: atomic SYS->UC CSR transfer mechanism.

High-level system composition

At a high level, the SoC is made of five cooperating layers:

  1. Platform and clocks AX7203 platform setup, input clock buffering, MMCM setup, and domain naming.

  2. LiteX base system CPU, CSR bus, timer, optional Ethernet/Etherbone, optional HDMI, and either integrated RAM or external memory.

  3. UberClock DSP block Multi-channel DSP datapath in the uc clock domain, plus configuration, debug selection, and interrupt/capture plumbing.

  4. UberDDR3 capture path Custom DDR3 controller and DMA writer that can capture UC-domain samples into side memory mapped into the SoC.

  5. Host and firmware tooling Build scripts, demo software, and UDP-based data extraction scripts under 3.build and 2.soc/2.sw.

Typical use cases

  • Build a bitstream with --with-uberclock to exercise the DSP/control path.

  • Build with --with-uberddr3 to enable high-speed capture into DDR3.

  • Use the CSR bank to tune NCOs, gains, routing, and debug paths.

  • Trigger DMA capture, then inspect or stream the captured memory externally.

Where the docs fit

  • The User Guide explains structure and intent.

  • The How-to pages cover repeatable workflows.

  • The Reference pages summarize software-visible contracts.

  • The API section exposes the Python classes and functions directly from the source code.