Board Model

adidt.model holds the dataclasses that carry a fully-assembled design on its way to DTS output. Both the XSA pipeline and the declarative adidt.system API produce the same BoardModel, which BoardModelRenderer then assembles into DTS strings.

Pipeline

XSA Pipeline                        Declarative System
─────────────                       ──────────────────
XsaPipeline.run()                   adidt.System(name, components)
  └─ AD9081Builder                    └─ system.connect_spi(...)
       .build_model()                    system.add_link(...)
           │                                 │
           └──────────────┬──────────────────┘
                          ▼
                     BoardModel
                (components + jesd_links)
                          │
                          ▼
                 BoardModelRenderer
                       .render()
                          │
                          ▼
           {clkgens, jesd204_rx/tx, converters}
                          │
                          ▼
                      DTS output

Components and JESD links carry pre-rendered DTS strings (produced by the declarative device classes in adidt.devices). The renderer groups components by SPI bus, wraps each group in &spi_bus { ... };, and concatenates per-direction JESD overlays. No Jinja2 involved.

Classes

class adidt.model.BoardModel(name: str, platform: str, components: list[ComponentModel] = <factory>, jesd_links: list[JesdLinkModel] = <factory>, fpga_config: FpgaConfig | None = None, metadata: dict[str, ~typing.Any]=<factory>, extra_nodes: list[str] = <factory>)

Bases: object

Unified board model that both the manual and XSA workflows produce.

A BoardModel is an editable snapshot of the complete hardware composition. After construction (from either workflow), callers may inspect and modify components, JESD links, and metadata before passing the model to BoardModelRenderer for DTS rendering.

name

Board/design name, e.g. "fmcdaq2_zcu102".

Type:

str

platform

Target platform, e.g. "zcu102".

Type:

str

components

Physical devices (clock chips, converters, etc.).

Type:

list[adidt.model.board_model.ComponentModel]

JESD204 link definitions (RX and TX).

Type:

list[adidt.model.board_model.JesdLinkModel]

fpga_config

Platform-level FPGA configuration.

Type:

adidt.model.board_model.FpgaConfig | None

metadata

Free-form dict for rendering metadata — date, config_source, base_dts_include, etc.

Type:

dict[str, Any]

class adidt.model.ComponentModel(role: str, part: str, spi_bus: str, spi_cs: int, rendered: str | None = None, template: str = '', config: dict[str, ~typing.Any]=<factory>)

Bases: object

One physical device on the board (clock chip, converter, etc.).

role

Logical role on the board — "clock", "adc", "dac", or "transceiver".

Type:

str

part

Part number string, e.g. "ad9523_1", "ad9680".

Type:

str

spi_bus

SPI bus label, e.g. "spi0", "spi1".

Type:

str

spi_cs

SPI chip-select index.

Type:

int

rendered

Pre-rendered DT node string emitted by the device’s render_dt() method. The renderer inserts this verbatim into the SPI-bus group for spi_bus.

Type:

str | None

template, config

Legacy fields (Jinja2 template name + context dict) kept for backwards compatibility with code that still constructs ComponentModel by hand. The current renderer ignores them when rendered is set.

class adidt.model.JesdLinkModel(direction: str, jesd_label: str, xcvr_label: str, core_label: str, dma_label: str | None, link_params: dict[str, int]=<factory>, dma_clocks_str: str | None = None, dma_interrupts_str: str | None = None, xcvr_rendered: str | None = None, jesd_overlay_rendered: str | None = None, tpl_core_rendered: str | None = None)

Bases: object

One JESD204 link (RX or TX) with its FPGA-side IP labels and rendered overlays.

direction

"rx" or "tx".

Type:

str

jesd_label

AXI JESD204 IP label, e.g. "axi_ad9680_jesd204_rx".

Type:

str

xcvr_label

ADXCVR IP label, e.g. "axi_ad9680_adxcvr".

Type:

str

core_label

TPL core IP label, e.g. "axi_ad9680_tpl_adc_tpl_core".

Type:

str

dma_label

AXI DMA IP label, e.g. "axi_ad9680_dma".

Type:

str | None

JESD framing parameters — keys F, K, M, L, Np, S.

Type:

dict[str, int]

dma_clocks_str

Optional clocks cells-string for the DMA overlay (inserted verbatim into the emitted overlay).

Type:

str | None

dma_interrupts_str

Optional interrupts cells-string for the DMA overlay. When set, the renderer emits a /delete-property/ interrupts; followed by an interrupts = ...; re-assignment. Use this when the sdtgen-generated IRQ number does not match the IRQ wire in the loaded bitstream.

Type:

str | None

xcvr_rendered, jesd_overlay_rendered, tpl_core_rendered

Pre-rendered DTS strings for the three FPGA-side IP overlays. Produced by adidt.devices.fpga_ip.

class adidt.model.FpgaConfig(platform: str, addr_cells: int, ps_clk_label: str, ps_clk_index: int | None, gpio_label: str)

Bases: object

Platform-level FPGA configuration.

platform

Target platform string, e.g. "zcu102", "vcu118".

Type:

str

addr_cells

Number of address cells — 1 for vcu118/zc706, 2 for zcu102/vpk180.

Type:

int

ps_clk_label

Processing-system clock label, e.g. "zynqmp_clk", "clkc".

Type:

str

ps_clk_index

PS clock index (e.g. 71), or None when the platform has no PS clock index.

Type:

int | None

gpio_label

GPIO controller label, e.g. "gpio", "gpio0".

Type:

str

class adidt.model.renderer.BoardModelRenderer

Bases: object

Renders a BoardModel into DTS node strings.

The output dict has the same shape that build() returns:

{"clkgens": [...], "jesd204_rx": [...], "jesd204_tx": [...], "converters": [...]}

This allows the existing DtsMerger to consume the output without changes.

render(model: BoardModel) → dict[str, list[str]]

Render model to DTS node strings (overlay mode).

Parameters:

model – The board model to render.

Returns:

Dict with keys clkgens, jesd204_rx, jesd204_tx, converters, each mapping to a list of DTS node strings.

Fields of note

  • ComponentModel.rendered — pre-rendered DTS string for this component. Declarative devices always populate this; the renderer inserts it verbatim into its SPI-bus group.

  • JesdLinkModel.{xcvr,jesd_overlay,tpl_core}_rendered — the three FPGA-side IP overlays for a single link. All three are produced by adidt.devices.fpga_ip devices.

  • JesdLinkModel.{xcvr,jesd_overlay,tpl_core}_config — legacy dict-typed fields kept for dict-based tests; unused by the current rendering path.