Xilinx Toolbox

The xilinx_toolbox plugin is a collection of functions designed specifically for Xilinx FPGA netlists. It normalizes primitives that behave differently from ordinary gates, and imports physical placement data from Xilinx constraint files.

This plugin is not built by default. Rebuild HAL with -DBUILD_ALL_PLUGINS=ON or -DPL_XILINX_TOOLBOX=ON, see Building HAL.

Why this matters

FPGA vendor primitives do not map cleanly onto HAL's one-gate-one-function model. A Xilinx LUT6_2 has two outputs computed from the same inputs; a shift register primitive holds many bits of state inside a single gate. Both are perfectly reasonable as hardware, and both break the assumptions that generic analyses make — a gate with two outputs confuses function extraction, and a multi-bit primitive hides an entire register from dataflow analysis.

Rewriting these primitives into equivalent, plain structures is what makes the rest of HAL's tooling work correctly on Xilinx designs. It costs you gate count and fidelity to the original bitstream, and buys you a netlist that behaves like every other netlist.

Run these transformations on a netlist.copy() if you need to preserve the original, see Netlist.

Normalizing primitives

from hal_plugins import xilinx_toolbox

xilinx_toolbox.split_luts(netlist)
xilinx_toolbox.split_shift_registers(netlist)

split_luts(nl) splits LUTs with two outputs into two separate LUT gates. It returns the number of split LUT6_2 gates, or None on failure. Afterwards each LUT drives exactly one output, so Boolean function extraction and subgraph analysis behave as expected.

split_shift_registers(nl) replaces shift register primitives with equivalent chains of flip-flops, returning the number of split registers or None on failure. This is the more consequential of the two: a shift register primitive is opaque to any analysis that reasons about flip-flops, so expanding it is what allows dataflow analysis to see the storage it contains and group it with related registers.

Importing placement data

parse_xdc_file(nl, xdc_file) parses a Xilinx .xdc constraint file and extracts the LOC and BEL placement data of each gate, returning True on success.

xilinx_toolbox.parse_xdc_file(netlist, "design.xdc")

Once imported, coordinates are available through Gate.get_location. This is worth doing whenever you have the constraint file, because physical proximity is an independent signal about logical grouping: gates belonging to the same word-level structure are typically placed close together, which gives you a hint that is completely uncorrelated with the netlist's connectivity.

See also

• Netlist Preprocessing — technology-independent cleanup passes
• Dataflow Analysis — the main beneficiary of expanded shift registers
• Gate — accessing the imported coordinates
• Gate Library Files — the Xilinx UNISIM and SIMPRIM libraries shipped with HAL