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

uberclock_soc

Package overview

uberclock_soc is the import root for the AX7203 LiteX integration package. Most useful public functionality is reached through the submodules documented below, especially soc.py for build entry and ubddr3.py / uberclock_core.py for major integration blocks.

Package API

class uberclock_soc.UberDDR3(*args: Any, **kwargs: Any)[source]

Bases: LiteXModule

UberDDR3 top-level integration block.

Use-case

This module wires a Verilog DDR3 controller (ddr3_top) into a LiteX SoC and provides two ways to write/read DDR.

CPU / software access (SYS domain):

  • Classic 32-bit Wishbone (LiteX standard) exposed as self.wb.

  • Width-converted up to the DDR bus width (UB_BUS_WIDTH_BITS).

  • Bridged into pipelined WB signaling used by the controller.

High-throughput capture / DMA (UC domain -> SYS domain -> DDR):

  • A UC-domain stream source generates DW-bit beats.

  • The source is either an internal ramp or packed design samples.

  • Stream crosses UC->SYS via AsyncFIFO.

  • zipdma_s2mm writes the stream into DDR through a shared crossbar.

Clock domains

  • “sys” : CPU, CSR bus, zipdma_s2mm, Wishbone fabric

  • “uc” : UberClock DSP / sample domain

  • “ub_4x” : DDR3 PHY clock

  • “ub_4x_dqs” : DDR3 PHY clock 90° shifted (DQS)

  • “idelay” : IDELAYCTRL reference clock

External inputs (from SoC)

  • cap_enable_uc : 1 = capture external design samples, 0 = use ramp

  • cap_beats_uc : number of DW-bit beats to write

  • cap_sample : the selected 12-bit sample (UC domain)

CSRs (SYS domain)

  • dma_req : strobe to start DMA write

  • dma_addr0/1 : 64-bit base address (packed from two 32-bit regs)

  • dma_inc : increment mode for DMA

  • dma_size : transfer size encoding (zipdma convention)

  • dma_busy/dma_err : status from zipdma

  • calib_done : DDR controller calibration complete

DEFAULT_SERDES_RATIO = 4
DEFAULT_CAP_BEATS = 256
DEFAULT_S2MM_FIFO_DEPTH = 256
class uberclock_soc.RampSource(*args: Any, **kwargs: Any)[source]

Bases: LiteXModule

Generates a 16-bit-lane ramp packed into bus_data_width-bit beats.

Packing:

  • Beat width: bus_data_width bits

  • Lanes: LANES = bus_data_width / 16

  • Lane i contains: (base_step + i) as a 16-bit value

  • base_step increments by LANES per accepted beat

class uberclock_soc.SamplePackerStream(*args: Any, **kwargs: Any)[source]

Bases: LiteXModule

Samples one value per UC cycle, packs 16-bit samples into bus_data_width beats.

Packing:

  • Each UC cycle produces one 16-bit sample (sign-extended from sample_width)

  • LANES = bus_data_width / 16 samples are packed into one beat

  • The first sample goes to lane 0 (bits [15:0]), then lane 1, …, lane LANES-1

  • After LANES cycles, one beat is enqueued into the beat FIFO

Output:

  • Beat FIFO drains using valid/ready

  • frames is the number of beats to capture/emit (one beat = LANES samples)

  • overflow=1 means the beat FIFO could not accept completed beats in time

class uberclock_soc.UCStreamMux(*args: Any, **kwargs: Any)[source]

Bases: LiteXModule

Selects between:

  • RampSource (internal test pattern)

  • External beat stream (typically SamplePackerStream)

Control:

  • start: starts ramp transfer when use_external=0

  • use_external: 0=ramp, 1=external stream

  • ramp_length_beats: ramp length in beats