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.Deviceoffset must match the correspondingAXIL_CONFIG_C(INDEX).baseAddrvalue generated in the VHDL crossbar, minus the parent’s base address (crossbars built withgenAxiLiteConfig(..., AXIL_BASE_ADDR_G, ...)hold absolute addresses).
AxiSocCore
python/axi_soc_ultra_plus_core/_AxiSocCore.py
AxiSocCore is the platform core PyRogue Device. It maps the AxiSocUltraPlusReg
register block of the AxiSocUltraPlusCore RTL; the DMA engine registers are not mapped.
Responsibilities:
Exposes the AXI-Lite register space of
shared/rtl/AxiSocUltraPlusReg.vhd.Provides
AxiVersion(0x0_0000), theAxiSysMonUltraScalesystem monitor (0x1_0000), the hiddenSysMonLvAuxDetLVAUX detector (0x1_1000), and theDmaIbAxisMon/DmaObAxisMonDMA AXI stream monitors (0x2_0000/0x3_0000).Takes
numDmaLanes(default 1), which sizes the DMA monitors and is checked againstAxiVersion.DMA_SIZE_Gat start (a mismatch prints a warning).Acts as the first-level child of the application
RFSoCdevice 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,
numDmaLanes = 2, # Must match DMA_SIZE_G
))
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:
Holds one surf
AxiStreamRingBufferper channel (Adc.Ch[i]at0x0_0000,Dac.Ch[i]at0x1_0000,0x1000apart) with trigger control (TrigBurst,ContinuousMode). The depth is fixed at build time (RAM_ADDR_WIDTH_G, read only) and there are no per-channel enables.Reports capture status (
BufferLength,TrigCntand the trigger and data FSM states); there are no fill level or overrun flags.Limits the outgoing frame rate with the
RateLimiter(AxiStreamFrameRateLimiterat0x2_0000). The frames reach the host-sideRingBufferProcessoron the DMA streams (ADC channels on TDEST0x00to0x0F, DAC channels on0x10to0x1F).
AppRingBuffer is instantiated inside the application Application device, not directly
in AxiSocCore. Each application repo sets the numAdcCh and numDacCh arguments to
match the board’s RFDC configuration.
RingBufferProcessor
python/axi_soc_ultra_plus_core/rfsoc_utility/_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 (waveform
and averaged FFT magnitude). File storage is done by the Root StreamWriter on a
separate branch of the same stream.
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) is the host-side
mapping of the board-side PyRFdc memory slave
(shared/Yocto/recipes-apps/pyrfdc/files/PyRFdc.cpp), which calls the Xilinx RFdc
driver API (XRFdc_*) rather than exposing the 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 added directly to the application Root, with memBase a
rogue.interfaces.memory.TcpClient to port 9002, where roguetcpbridge on the board
serves PyRFdc. It is not behind the AXI-Lite crossbar: index 1 of the
AxiSocUltraPlusReg crossbar holds only the read-only PYRFDC_CONFIG ROM that
roguetcpbridge reads to construct PyRFdc. Application Root.start() sequences
clock initialization before calling Rfdc.Init() to program the IP core.
Rfdc.Init() resets every enabled tile once (DAC tiles first, and inside each
converter type the clock distribution sources before their members), waits for state 15
with the PLL locked on every tile, re-applies the settings written in this session, and
raises one exception naming every tile that missed the wait. The operator commands
behave as follows:
Reseton a tile,ResetAllAdcandResetAllDacrun the same sequence for one tile or one converter type, and also re-apply any tile the restart knocked (see PyRFdc Reset and Restart Process). Settings written in the session are written back in a fixed order. A register that a restart reloads returns to its Vivado value when the session never wrote it; a mixer that was never committed is returned to the Vivado NCO, and a QMC that was never committed to its power-up default. A bare restart does not restore mixer NCO settings, soResetfollowed byApplyConfigreturns to the Vivado baseline only for settings not written in the session.A committed PLL (
PllConfigwithPllConfigUpdate) is written back when the hardware differs from it. The commit reprograms the PLL live and restarts the tile only from state 6 (states 1 to 5 do not run), and a tile left like that can stall at state 7 when a neighboring tile restart knocks it. Every PLL commit, from the operatorPllConfigUpdateor from the write-back, is therefore followed by aStartUpof the same tile (state 1 to 15, settings kept), which advances that tile’s restart record by one, and then by the wait for every enabled tile. A commit on DAC tile 0 takes the same path: that tile distributes the clock to the others, which are waited for and re-applied if the restart knocked them.StartUpon a tile,StartUpAllAdcandStartUpAllDacare the default recovery: they restart from state 1, keep every setting and wait for every enabled tile. They write nothing back.ApplyConfigwaits for every enabled tile, then writes back the settings written in this session on demand, without a restart unless a committed PLL differs from the hardware.Settings that were not surveyed on the board are written back only when the operator wrote them:
the FabClkOutDiv, PwrModeSettings, calibration coefficient override, DisableFreezePin, FreezeCalibration and DACVOP settings
the threshold clear mode words
an external ClockSource
the QMC phase settings of blocks that are not an IQ pair
the DAC mixer and interpolation factor settings that the tile refuses
the ADC observation channel settings (
DecimationFactorObs,FabRdVldWordsObsand the observation FIFO enable, whichSetupFIFOObsandSetupFIFOBothalso drive), which were read on SlacRfmcCarrier onlyevery tile other than the ones used as representatives
A setting counts as written only when its write returned without an error on an enabled device. A value that pyrogue or the memory slave refuses records nothing and keeps the setting’s earlier record. A write under a disabled block or device (for example from
LoadConfigof a file that covers every block) is ignored by the hardware, records nothing and also keeps the earlier record. ALoadConfigvalue is recorded once pyrogue accepts it, even if the bulk write that follows is refused. An unconfirmed write on an enabled device is not recorded and drops that setting’s earlier record (for a commit, the earlier committed snapshot): aset()made withwait=False(or the deprecatedcheck=False) returns before its write is confirmed, and any write or commit made while the hiddenIgnoreMetalErrordebug setting is on cannot be told from success. A later restart then returns the setting to its Vivado value, as for a setting never written, until a confirmed write records it again. A recorded setting whose device is disabled when the write-back runs, and a committed DACMixerwhose block readsDataPathMode 4(full bandwidth bypass refuses a mixer commit) at that time, are skipped with a logged warning and are not reported as a tile failure.The FIFO words
SetupFIFO,SetupFIFOObsandSetupFIFOBothof a tile, and theRfdcwordsSetupFIFOAllAdc,SetupFIFOAllDac,SetupFIFOObsAllAdcandSetupFIFOBothAllAdc, takeFalse(0, disables) orTrue(3, enables). They are written back in the order they were written, the newest of a tile word and itsRfdctwin winning. The oldUNDEFINEDlabel and the value 2 are gone from the enum, so a saved configuration holdingUNDEFINEDno longer loads, while a raw write of 2 still enables the FIFO.A
Mixer.FreqorMixer.PhaseOffsetset()(or GUI edit) commits the mixer throughUpdateEventright after its write, so no separate commit is needed. Set the block’sMixer.AutoUpdate(defaultTrue) toFalseto stage several fields and commit them with oneUpdateEvent. The other mixer fields, aLoadConfig, aset()withwait=Falseandpost()still need an explicitUpdateEvent, and a refused commit raises to the caller ofset().The block
Mixerdevice is enabled whenever the block sample rate is non-zero. It used to followBlockStatus.MixerMode, which reads 0 for the bypass mixers of this design, so aMixerwrite now reachesPyRFdcand can be refused, for example on a DAC block in full bandwidth bypass (DataPathMode 4).UpdateIsEnabled()re-reads only the tile, block andMixerenable chain, never an operator setting, and does not refresh the other variables (useReadAll). It returnsNoneand gives the same result when run twice. A failed read of a tile enable flag (CheckAdcTileEnabledorCheckDacTileEnabled) raises that read’s error directly, and every other failed read is collected into oneRuntimeErrorthat lists them.Mts.SyncAdcTilesandMts.SyncDacTilescheck, at once and without waiting, thatAdcTiles(DacTiles) is not zero and that every tile of the mask plus the reference tile (AdcRefTileorDacRefTile) is enabled and passes the same state 15, Restart clear and PLL lock test as theInitwait. They then run the multi-tile sync once withIgnoreMetalErrorheld off and checkAdcMtsValid(DacMtsValid). A sync on a disabledRfdcdevice is refused at once, before any tile is checked. A refusal names every failing tile, in the key=value form of the reset diagnostics, and nothing is written.Initand theReset,StartUp,ApplyConfigandPllConfigUpdatecommands never sync.AdcMtsValidandDacMtsValidread 1 only after a successful sync. A restart of the source tile of a clock distribution clears the flag of every converter type that has a tile in that distribution: on SlacRfmcCarrier, DAC tile 0 is the source for DAC tiles 1 to 3 and ADC tile 3, soResetAllDacand a DAC tile 0 restart clear both flags. A restart of member tiles, or of a source with no member of the other converter type, clears only the flag of their own converter type: a DAC tile 1ResetclearsDacMtsValidonly and an ADC tile 2ResetclearsAdcMtsValidonly. On a device below Gen3 every restart clears both flags. A flag also reads 0 while any enabled tile of its group (the tile mask plus the reference tile) is restarting or below state 15; a restart thatPyRFdcdid not command and that has already finished is not detected, and the read never changes the latched value. The member rule assumes that restarting member tiles does not disturb a tile of the other converter type. That holds for this layout; on another layout the live check, which sees only a restart still in progress, is the only safeguard.The hidden
ResetRaw,StartUpRaw,ResetAllAdcRaw,ResetAllDacRaw,StartUpAllAdcRawandStartUpAllDacRawcommands are bare restarts: they do not wait for the other tiles and write nothing back. The hiddenSyncAdcTilesRawandSyncDacTilesRawcommands are the bare multi-tile sync: they do not check the mask, andPyRFdcstill refuses them while a tile of the group is not ready.Rfdcraises its own transaction timeout to 32 s, so an application does not need a large Root timeout. The longest single transaction is the restart of all four tiles of one converter type: 4 tiles × 3 s of driver waits = 12 s. The floor stays at 32 s, well above the 12 s, so existing applications see no change in timeout behavior.
Source files:
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(serverList='localhost:9099', ui=uiFile, title='RFSoC Demo')
Its signature is runPyDM(serverList='localhost:9090', ui=None, title=None, sizeX=800,
sizeY=1000, maxListExpand=5, maxListSize=100, numAdcCh=1, numDacCh=1): it connects to
a running Rogue server through serverList and takes no root argument. Its default
ui is a pydmTop.py that the package does not ship, so pass ui explicitly.
The reference application’s devGui.py does not use it. It constructs the Root in
a with block (which starts it) and calls pyrogue.pydm.runPyDM() with
serverList=root.zmqServer.address and a display_factory that builds GuiTop
with numAdcCh and numDacCh. The ZMQ server is the pyrogue.interfaces.ZmqServer
that the application Root.__init__ adds (127.0.0.1, port zmqSrvPort, default
9099).
The axi_soc_ultra_plus_core.rfsoc_utility.pydm subpackage contains only runPyDM.
The display panels live in axi_soc_ultra_plus_core.rfsoc_utility.gui: GuiTop has
System, Debug Tree, ADC Waveforms and DAC Waveforms tabs, the waveform tabs being
LiveDisplay panels of the RingBufferProcessor data. They are board-agnostic (the
channel counts come from numAdcCh and numDacCh) and reused across every
Simple-*-Example application.