Platform Architecture
This page is the platform-level architecture narrative for axi-soc-ultra-plus-core.
The platform provides the core infrastructure (AXI-Lite register bridge, DMA engine,
SSR gearboxes, ring-buffer IP, and signal-generator IP) that every Simple-*-Example
application repo builds upon. Readers looking for per-board details should consult
Supported Boards and each application repo’s own documentation.
System overview
The platform connects a remote host machine to a Zynq UltraScale+ RFSoC device over TCP.
The PS (Processing System) runs Linux; the PL (Programmable Logic) implements the FPGA
design. All register access and DMA data transfers cross the PS-to-PL boundary through the
AxiSocUltraPlusCore block.
┌────────────────────────────────────────────────────────────────────────────┐
│ Host Machine (Remote Client) │
│ software/scripts/devGui.py | software/notebooks/rfsoc_example.ipynb │
└────────────────────────┬───────────────────────────────────────────────────┘
│ TCP (ports 9000/9001 AXI-Lite, 9002 RFDC,
│ 10000+ AXI Stream ring buffers)
┌────────────────────────▼───────────────────────────────────────────────────┐
│ RFSoC Board (PS + PL, Zynq UltraScale+) │
│ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ PL (FPGA) │ │
│ │ │ │
│ │ ┌──────────────────┐ ┌──────────────────┐ ┌────────────────────┐ │ │
│ │ │ AxiSocUltra │ │ RfDataConverter │ │ Application │ │ │
│ │ │ PlusCore (HW) │ │ (RFDC wrapper) │ │ (app-specific) │ │ │
│ │ │ [submodule] │ │ │ │ │ │ │
│ │ │ │ │ │ │ ┌─────────────┐ │ │ │
│ │ │ DMA engine │ │ dspClk domain │ │ │AppRingBuffer│ │ │ │
│ │ │ dmaClk domain │ │ axilClk domain │ │ └─────────────┘ │ │ │
│ │ └─────────┬────────┘ └─────────┬────────┘ │ ┌─────────────┐ │ │ │
│ │ │ AXI-Lite XBAR │ │ │ SigGen │ │ │ │
│ │ │ (3 masters) │ dspAdc/Dac│ │ (DacSigGen) │ │ │ │
│ │ └─────────────────────┴──────────►│ └─────────────┘ │ │ │
│ │ └────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────┘
Three major PL blocks make up each application design:
AxiSocUltraPlusCore: the platform core, provided as a git submodule. It implements the PS-to-PL AXI-Lite bridge, the DMA engine, and the system monitor. Application repos do not modify this block.
RfDataConverter: provided by each application repo (
firmware/shared/rtl/RfDataConverter.vhd); wraps the Xilinx RF Data Converter IP core. GeneratesdspClkfrom a PLL on the PL reference clock, applies ADC P/N swap and polarity corrections, and gear-boxes theadcClock(416.667 MHz) RFDC output down to the 312.5 MHz DSP clock domain.Application: the board-specific application logic. Contains the second-level AXI-Lite crossbar,
AppRingBuffer(ADC/DAC capture), andDacSigGen(waveform generator). EachSimple-*-Examplerepo provides its ownApplication.vhd.
Clock domains
The design has four clock domains. The XDC constraints file in each application repo
declares all four as asynchronous clock groups (lines 13 to 17 of
SimpleRfSoc4x2Example.xdc): the two outputs of the AxiSocUltraPlusCore PLL
(dmaClk, axilClk) and the two outputs of the RfDataConverter PLL (adcClock,
dspClk).
dmaClk(250 MHz)The
AxiSocUltraPlusCoresystem clock (DMA_CLK_FREQ_CinAxiSocUltraPlusPkg). The DMA engine, the PS-to-PL AXI-Lite bridge, the core’s own registers, and theAppRingBufferDMA output all run in this domain.axilClk(100 MHz)The application AXI-Lite control-plane clock, driven by the
auxClkoutput ofAxiSocUltraPlusCore. PS register transactions cross the PS-to-PL boundary indmaClkand are moved intoaxilClkby anAxiLiteAsyncinside the core before reaching the application window. The top-level crossbar, the RFDC AXI-Lite port, and the application crossbar run in this domain; the constantAXIL_CLK_FREQ_C(100.0E+6, declared inAppPkg.vhd) records its frequency.dspClk(312.5 MHz)The DSP and DAC sample-rate clock. The
Applicationblock,AppRingBuffer,DacSigGen, and the 256-bitSlv256Arraysample bus all run ondspClk.RfDataConvertergeneratesdspClkinternally from a PLL driven by the 500 MHzplClkP/plClkNPL reference clock input.adcClock(416.667 MHz)The RFDC ADC AXI Stream clock, generated by the same
RfDataConverterPLL asdspClk. The Xilinx RF Data Converter IP delivers digitized samples onadcClock. TheSsr12ToSsr16Gearboxprimitive converts 12 samples per cycle at 416.667 MHz into 16 samples per cycle atdspClk(312.5 MHz), crossing the domain boundary in the process.
All clock-domain crossings (CDC) must use surf synchronizer or async primitives (for
example Synchronizer, AxiLiteAsync) or the Ssr12ToSsr16Gearbox. No direct
flip-flop paths are permitted between the four asynchronous groups.
The Application PyRogue device must be enabled only after dspClk is stable.
The Root.start() startup sequence enforces this order: AxiSocCore.UserRst →
InitClock → DspRstWait → Application.enable → Rfdc.Init → MTS sync →
config load → DacSigGen waveform load.
DMA model
The AxiSocUltraPlusCore DMA engine moves ADC and DAC ring-buffer data between the PL
and PS DDR over AXI Stream. The lane count is set by the DMA_SIZE_C constant in each
application’s AppPkg.vhd (conventional value: DMA_SIZE_C = 2).
Lane assignment:
Lane 0: ADC/DAC ring-buffer data.
AppRingBufferwrites captured samples into inbound DMA frames; the PS forwards each DMA channel over a TCP stream port pair starting at10000 + 512*lane + 2*tdest.Lane 1: Hard-wired loopback for DMA path debug. The top-level VHDL wires
dmaIbMasters(1) <= dmaObMasters(1)directly.
On the Linux side, the aes-stream-drivers kernel module provides the device nodes used
by the Rogue framework:
/dev/axi_memory_map: memory-mapped AXI-Lite register access/dev/axi_stream_dma_0: AXI Stream DMA channel for ring buffer data
The application Root (PyRogue) connects to the board through Rogue’s TCP bridge rather
than through these device nodes directly. The roguetcpbridge service on the board
bridges the device nodes to Rogue TCP servers; the host connects as a TCP client.
Host-side drop FIFOs (adcDropFifo, dacDropFifo, maxDepth=1) prevent host-side backpressure from stalling the firmware DMA path.
Adding DMA lanes requires updating DMA_SIZE_C in AppPkg.vhd and the corresponding
stream wiring in the application _Root.py.
For the host-side Rogue stream pipeline and the RingBufferProcessor API, see
PyRogue API Reference.
Sample bus
ADC and DAC sample data between the RFDC wrapper and the Application block flows on the
Slv256Array bus, a 256-bit parallel bus clocked at dspClk (312.5 MHz). The type
is defined in surf.StdRtlPkg.
Each 256-bit word carries SAMPLE_PER_CYCLE_C = 16 samples of 16 bits each:
-- 4 ADC input channels, one Slv256 per channel
dspAdc : in Slv256Array(3 downto 0);
-- 2 DAC output channels, one Slv256 per channel
dspDac : out Slv256Array(1 downto 0);
The constant SAMPLE_PER_CYCLE_C (declared in AppPkg.vhd) links VHDL generics
(ADC_SAMPLE_PER_CYCLE_G, DAC_SAMPLE_PER_CYCLE_G, SAMPLE_PER_CYCLE_G) to the
smplPerCycle argument of the Python DacSigGen (rfsoc_utility.SigGen) device
inside Application. Changing this constant requires
synchronized updates in both the VHDL package and the Python device tree; the two values
are not cross-checked automatically at build time.
For the full AppPkg constants layout and how they feed the crossbar configuration, see
Register Map.
AXI-Lite hierarchy summary
All register access flows from the PS ARM core through the AxiSocUltraPlusCore AXI-Lite
bridge into a two-level crossbar tree instantiated in the application’s top-level VHDL
entity:
Top-level crossbar decodes the address space into three slaves:
HW_INDEX_C=0(board-specificHardwareblock; unconnected on the RFSoC 4x2),RFDC_INDEX_C=1(RFDC IP registers), andAPP_INDEX_C=2(application logic).Application crossbar (inside
Application.vhd) further decodes the application address space:RING_INDEX_C=0(AppRingBufferregisters) andDAC_SIG_INDEX_C=1(DacSigGenregisters).
The Python pr.Device tree mirrors this hierarchy exactly. Each device’s address
within the PL AXI-Lite window (its offset plus its parents’ offsets below the RFSoC
device) must equal the AXIL_CONFIG_C(INDEX).baseAddr value generated by the
genAxiLiteConfig VHDL call. For the full addressing pattern, constant definitions, and
Python offset examples, see Register Map.
Further reading
Register Map: AXI-Lite addressing model,
genAxiLiteConfigpattern,AppPkgconstants, and theSlv256Arraysample bus definitionPyRogue API Reference: platform PyRogue classes (
AxiSocCore,AppRingBuffer,RingBufferProcessor,Rfdc, and the PyDM GUI launcher)Supported Boards: the
Simple-*-Exampleapplication repos with their board models, Xilinx part numbers, and target directory names