PyRogue API Reference

This page documents the platform-level PyRogue classes provided by the axi_soc_ultra_plus_core Python package (installed from the firmware/submodules/axi-soc-ultra-plus-core/ submodule). These classes form the foundation that every Simple-*-Example application repo extends.

Application-level PyRogue (the per-board Root / RFSoC / Application device tree) is documented in the reference pages of each application repo.

Device tree pattern

The PyRogue device tree is a direct mirror of the RTL AXI-Lite address hierarchy. Each pr.Device subclass holds its offset relative to its parent; the absolute address of any register is the sum of offsets along the path from root to leaf.

class MyDevice(pr.Device):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)

        self.add(SomeChild(
            offset = 0x00_000000,
            param  = value,
        ))

Key rules:

• Always pass **kwargs — never enumerate base-class arguments explicitly.

• Use self.add(...) for every child device or variable.

• Offset addresses use hex with underscore byte groupings: 0x00_000000, 0xA000_0000, 0x04_0000_0000.

• Each pr.Device offset must match the corresponding AXIL_CONFIG_C(INDEX).baseAddr value generated in the VHDL crossbar.

AxiSocCore

python/axi_soc_ultra_plus_core/_AxiSocCore.py

AxiSocCore is the platform core PyRogue Device. It wraps the AXI-Lite bridge from the Zynq PS to the PL, the DMA engine, and the SysMon subsystem.

Responsibilities:

• Exposes the AXI-Lite register space of the AxiSocUltraPlusCore RTL block.

• Provides AxiVersion, system monitor (SysMonLvAuxDet), and DMA status registers.

• Acts as the first-level child of the application RFSoC device at a fixed offset determined by the platform crossbar.

Typical instantiation (inside the application RFSoC device):

import axi_soc_ultra_plus_core as soc_core

self.add(soc_core.AxiSocCore(
    offset = 0x0000_0000,
    expand = True,
))

AppRingBuffer

python/axi_soc_ultra_plus_core/rfsoc_utility/_AppRingBuffer.py

AppRingBuffer is the PyRogue Device that controls the ADC and DAC capture ring buffers in the RTL. It provides AXI-Lite register access to the ring buffer control and status, and is the source of the DMA inbound data stream.

Responsibilities:

• Sets the ring buffer trigger mode, depth, and channel enables.

• Reports capture status (fill level, overrun flags).

• Coordinates with the host-side RingBufferProcessor to frame captured ADC/DAC samples.

AppRingBuffer is instantiated inside the application Application device, not directly in AxiSocCore. Each application repo sets the numAdcCh and numDacCh generics to match the board’s RFDC configuration.

RingBufferProcessor

python/axi_soc_ultra_plus_core/hardware/_RingBufferProcessor.py

RingBufferProcessor is a host-side Rogue stream receiver. It sits at the end of the DMA TCP stream pipeline and processes captured ADC or DAC frames for display or storage.

The stream is wired in the application Root using the Rogue >> operator:

# Connect TCP stream → drop FIFO → ring buffer processor
self.ringBufferAdc[i] >> self.adcDropFifo[i] >> self.adcProcessor[i]

The drop FIFO (maxDepth=1) prevents host-side backpressure from stalling the DMA path inside the firmware.

RFDC API

python/axi_soc_ultra_plus_core/rfsoc_utility/_Rfdc.py

The Rfdc device (and its children RfdcTile and RfdcBlock) wraps the Xilinx RF Data Converter IP core register map. It exposes:

• Per-tile and per-block ADC/DAC configuration registers.

• Multi-Tile Synchronization (MTS) control.

• Sample rate, decimation/interpolation factor, and mixer frequency settings.

The Rfdc device is instantiated at the RFDC crossbar slot (index 1 in the top-level crossbar). Application Root.start() sequences clock initialization before calling Rfdc.Init() to program the IP core.

Source files:

• python/axi_soc_ultra_plus_core/rfsoc_utility/_Rfdc.py

• python/axi_soc_ultra_plus_core/rfsoc_utility/_RfdcTile.py

• python/axi_soc_ultra_plus_core/rfsoc_utility/_RfdcBlock.py

PyDM GUI launcher

The platform package provides a PyDM-based GUI entry point:

from axi_soc_ultra_plus_core.rfsoc_utility import pydm as rfsoc_pydm
rfsoc_pydm.runPyDM(root=root, title='RFSoC Demo')

The GUI launcher is invoked by each application repo’s devGui.py script after constructing the Root object and calling root.start(). It launches the pyrogue.pydm.runPyDM() GUI backed by the platform ZMQ server at the address configured in Root.__init__.

The axi_soc_ultra_plus_core.rfsoc_utility.pydm subpackage contains PyDM display panels for ADC/DAC ring buffer waveforms, RFDC tile configuration, and ring buffer control — all board-agnostic and reused across every Simple-*-Example application.