Toolchain integration

Hardware Integration

Connect your Livt design to FPGA tools and prepare it for implementation on hardware.

Hardware integration takes a Livt design from generated HDL into an FPGA toolchain. Livt prepares the HDL, wrappers, and integration files; the vendor tools then provide the synthesis, implementation, timing analysis, and programming-file generation needed to run the design on a device.

You can create a standalone project for a complete FPGA design or export a component for use in a larger system. In Visual Studio Code, the Vendor node in the Livt Project view brings these integrations together with their configuration and generated files. This page follows that workflow using a Vivado project as an example.

Prepare your design

Begin with a design that builds successfully and whose behaviour has been checked in simulation. Keep synthesizable components in your source directory and simulation scenarios in the test directory. Simulation-only operations should remain outside the synthesis path, even when you include tests in the vendor project.

The entry component defines the design that you want to integrate. Set project.component in livt.toml, or choose a component specifically for the vendor template. Review its external signals: clocks and resets establish the execution context, while inputs, outputs, and interfaces connect the design to the rest of the system. Public stored fields can also create ports, so inspect the generated boundary instead of assuming that only constructor parameters appear there.

Passing a simulation checks the behaviour exercised by that test. It does not establish that the design fits the selected device or meets physical timing. Those checks come later in the vendor tools. See Testing and Simulation for the verification workflow and Build results for inspecting build output.

Choose a hardware integration

Choose a standalone integration when the Livt design will be the basis of an FPGA project. Choose an IP integration when another project will consume the component. The distinction determines what Livt prepares: an implementation project, a portable HDL bundle, or a vendor-specific IP package.

ToolchainStandalone templateIP template
AMD Vivadovivado creates an openable FPGA project.vivado-ip packages the component as Vivado IP.
GOWIN EDAgowin creates and runs an FPGA project.gowin-ip creates a portable VHDL bundle for a consuming project.
Lattice Radiantradiant creates and runs an FPGA project.radiant-ip packages the component as installable Radiant IP.

In the Livt Project view, expand the intended project, right-click Vendor, and choose Add Vendor Template…. The picker lists the templates available in your installed toolchain and describes what each produces. Selecting a template starts its generation workflow and adds missing configuration to the manifest. Review the target settings before relying on the resulting project; scaffolded defaults may not match your board.

Vendor selected in the HardwareDemo project, with Add Vendor Template available in its context menu.
Start from the project’s Vendor node.
Add Vendor Template picker listing standalone and IP templates for GOWIN, Lattice Radiant, and AMD Vivado.
Choose the integration that matches the consuming toolchain and the kind of output you need.

Configure the target

The manifest keeps the integration settings with the project. Shared Vivado settings belong under [vendor.vivado], while [vendor.vivado.project] controls the standalone project and [vendor.vivado.ip] controls IP packaging. For example, a standalone configuration can select a component and an automatic wrapper explicitly:

toml
[vendor]
active = "vivado"

[vendor.vivado]
part = "xc7z020clg400-1"

[vendor.vivado.project]
component = "CounterTop"
wrapper = "auto"
top = "countertop_wrapper"
include_tests = true

Replace part with the exact device fitted to your board, including its package and speed grade. The part shown here is an example. An IP packaging project also needs a valid part for its tool run, but the consuming project determines the final device context. Other vendors have their own device settings; review the sections created by their templates rather than copying Vivado settings into them.

The component value chooses the Livt component to export and can override project.component for this integration. With wrapper = "auto", Livt generates the VHDL boundary; top names its top-level entity. If the extension needs a component selection, it asks which component to use and whether to save that choice for the project, save a vendor override, or use it for this invocation.

For the Vivado templates, include_tests = true adds test files to the simulation fileset while keeping design files in the main source fileset. This makes vendor-side simulation convenient without making the test components part of the hardware design. Set it to false when the handoff should omit those test files.

HardwareDemo manifest beside its active vivado template, showing the part, automatic wrapper, top entity, and test inclusion settings.
Review the generated configuration and replace defaults with the settings for your design and device.

Select the active template

A project can keep several vendor integrations. Right-click the template you intend to target and choose Set as Active; a single configured template is active automatically. The selection is recorded as vendor.active and lets ordinary builds use the corresponding vendor-specific memory attributes. Without an active selection, multiple configured templates produce a warning and use the default attribute policy.

An explicit export such as livt vendor vivado-ip selects that template before building its output. Existing target and toolchain settings remain supported, with active taking precedence. Changing the selection invalidates affected build output automatically, so a manual clean is unnecessary.

Generate and open the project

After reviewing and saving the manifest, right-click the configured template and choose Regenerate Vendor Template. Livt builds the required HDL, prepares the integration files, and runs the template’s tool steps. Read the command output to confirm the selected component, part, top, and wrapper, and check that generation completed successfully.

Expand the template under Vendor to inspect its workspace. Each integration has a separate directory under .livt/vendor/<vendor>/, with design for standalone projects and ip for IP integrations. The Vivado standalone example produces .livt/vendor/vivado/design/project.tcl, an automatic wrapper, a tool log, and a work directory containing the .xpr project. Open that project in Vivado to continue the implementation workflow.

Expanded Vivado workspace with HardwareDemo.xpr, project.tcl, vivado.log, and the generated countertop_wrapper.vhd open in VS Code.
Inspect the generated wrapper and locate the openable project under work before continuing in Vivado.

For Vivado IP, the corresponding project lives under .livt/vendor/vivado/ip/work, and the packaged output lives under .livt/vendor/vivado/ip/package. Add that package to the consuming project’s IP workflow. Other templates produce the files appropriate to their tools; use the command output and the template’s workspace to locate the result.

Resolve tool problems

Generated scripts or HDL can exist even when the vendor tool did not run successfully. If the extension reports a missing tool, install it or use Configure Tool Path, then retry. Tool resolution checks an explicit manifest setting first, followed by the corresponding environment variable and then PATH. A stale explicit path therefore needs correcting even if another installation is available.

For Vivado, these settings are vendor.vivado.path and LIVT_VIVADO_PATH. Prefer a machine-specific environment setting when sharing the project. The environment inherited by VS Code can differ from its terminal environment; restart VS Code after changing it if necessary. If the tool starts but fails, use Show Output and inspect the generated log for details such as an unsupported part or a licence problem. Creating the Vivado project does not by itself run synthesis or produce a bitstream.

Connect the hardware interfaces

An automatic wrapper provides a starting point for connecting the generated design. Inspect its entity ports before adding it to a board project: check signal directions, clock and reset connections, interface expansion, and any ports created for public stored fields. This is also the point to check that the selected top is the design component you intended to export.

Use a custom VHDL wrapper when the board needs specific port names, clocking resources, reset adaptation, I/O buffers, or connections to vendor IP. Keep this file with your authored source, for example under src/, and set wrapper to its project-relative path. Set top to the wrapper’s entity name. The wrapper can then connect the Livt-generated design to device-specific primitives while your Livt interfaces describe the signals used by the application.

toml
[vendor.vivado.project]
component = "CounterTop"
wrapper = "src/board_top.vhd"
top = "board_top"
include_tests = false

Integrate register interfaces

Components using Livt.HxS follow the same standalone and IP workflows. Keep the memory-mapped bus visible at the component boundary and test the register contract before exporting it. Register addresses, bit positions, reset values, and delegated ranges form an interface shared with software and parent designs; changing them may require a coordinated update. See Register Interfaces for the annotation and bus-testing workflow.

Check constraints and implementation

Before implementing a board-level design, add constraints for its actual hardware. Define the clocks and their periods, assign top-level ports to package pins, and select the correct I/O standards. Generated clocks and timing exceptions must reflect the real clocking and signal relationships in the design. Livt source and an automatically generated wrapper do not supply that board-specific information.

Keep the constraint files under version control and ensure that the vendor project loads them. After synthesis and implementation, review timing, resource utilisation, inferred memories, clock-domain crossings, and tool warnings. Check for unconstrained paths as well as reported timing violations; a passing result is only meaningful when the intended paths are constrained. A renamed or widened port also requires a review of wrapper connections, pin assignments, timing constraints, and consuming IP projects.

Check memory placement

Libraries express portable storage intent through MemoryStyle. The active vendor selection determines the placement attributes emitted for that intent. For example, GOWIN Block placement uses syn_ramstyle = "block_ram", while Auto emits no placement attribute. Where a vendor-specific mapping is unavailable, Livt preserves the requested style with its default attribute and warns about the fallback. The default policy uses ram_style = "block" or "distributed"; it does not silently turn an explicit request into Auto.

These attributes are hints to synthesis. They do not change read latency, reset behaviour, initialisation, or ownership, and they do not turn an explicitly array-backed implementation into RAM. Inspect the synthesis report to confirm that the selected device and access pattern produce the intended memory resources.

Regenerate and maintain the integration

Regenerate the integration after changing the exported component, its ports, the target device, or the wrapper settings. Treat .livt/vendor as generated workspace: edits made directly to generated wrappers, scripts, or project files can be lost during regeneration. Keep the durable inputs—Livt source, custom wrappers, constraints, and configuration—outside that workspace and under version control. If you adjust a generated project interactively, record the required changes in maintained inputs or a repeatable setup step before regenerating it.

For a hardware release, build and test the Livt design, regenerate its integration, run the required vendor implementation flow, and archive the resulting reports and programming files together with the source revision and tool configuration. Once this works interactively, automate the same steps so that the next release can be reproduced. Continue with Use commands in automation for integrating these checks into your build process.