Vendor Integration

Livt projects can enter existing FPGA and ASIC toolchains while keeping the design boundary clear and reviewable.

Vendor integration is about keeping that handoff clean: source code stays in Livt, tests stay available for simulation, and vendor-specific project files live in a predictable workspace.

Build Artifacts

The normal flow is:

1. Write Livt source.
2. Build the project.
3. Run simulation.
4. Create vendor project files.
5. Open the vendor project for synthesis, implementation, packaging, or downstream integration.

The livt vendor command creates vendor integration files under .livt/vendor. This folder is the workspace for project scripts, openable vendor projects, logs, and packaged output.

livt vendor vivado
livt vendor vivado-ip

Synthesis Boundaries

Keep synthesizable design code separate from test and simulation code. A source component should avoid simulation-only APIs unless it is explicitly not part of the synthesis path.

Good boundaries make vendor integration simpler:

• src/ contains design code
• tests/ contains test components and simulation scenarios
• top-level constructors expose clear physical signals
• interfaces group protocol signals
• top-level ports are easy to review

Top-Level Components

The top-level component is the bridge to the vendor project. Keep its constructor clear and hardware-facing:

component Top
{
    app: AppCore

    new(clk: clock, rst: reset, rx: in logic, tx: out logic)
    {
        this.context.clk = clk
        this.context.rst = rst
        this.app = new AppCore(rx, tx)
    }
}

Avoid hiding board-level signals deep inside the design. A reviewer should be able to open the top-level component and understand the external contract.

Vendor Templates

Livt currently provides two Vivado-oriented vendor templates:

• vivado creates an openable standalone Vivado project.
• vivado-ip creates an openable Vivado IP project and package output.

Both templates use the shared Vivado settings in livt.toml. You can pass the target part directly on the command line:

livt vendor vivado-ip xc7a100tcsg324-1

If no part is passed, Livt uses the configured part or scaffolds a default value into livt.toml. Before the vendor tool is launched, the command prints a configuration overview so the selected template, part, top, wrapper, and test settings are visible.

Vivado Standalone Projects

Use the standalone template when the Livt project should become a normal Vivado project:

livt vendor vivado

The project is created under .livt/vendor/work and can be opened in Vivado after the command succeeds. This flow is useful for board-level applications, experiments, and projects where Vivado owns the final implementation flow.

Vivado IP Packages

Use the IP template when the Livt project should be packaged as reusable Vivado IP:

livt vendor vivado-ip

The Vivado project is created under .livt/vendor/work, and the packaged IP output is created under .livt/vendor/package. The consuming Vivado project selects the final board or device context; the IP project only needs a valid packaging part for the tool run.

Auto and Custom Wrappers

By default, Livt can create an automatic wrapper for the selected component. The auto wrapper exposes the component constructor parameters as the hardware boundary and lives in .livt/vendor because it belongs to the vendor workspace.

Use a custom wrapper when a project needs board-specific naming, reset handling, special clocking, or hand-written vendor connections. Custom wrappers belong in src/ and are selected in livt.toml.

Configuration

A Vivado IP project can use:

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

[vendor.vivado.ip]
component = "WebApp"
wrapper = "auto"
top = "webapp_wrapper"
include_tests = true

A standalone Vivado project uses the same shared part setting and a project section:

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

[vendor.vivado.project]
component = "WebApp"
wrapper = "auto"
top = "webapp_wrapper"
include_tests = true

If these settings are missing, livt vendor adds sensible defaults without removing existing project settings.

Tests in Vendor Projects

Both Vivado templates can include test files for simulation. With include_tests = true, design files are used for the main project and test files are added to the simulation setup. This keeps synthesis boundaries clear while still making project-level simulation convenient.

Vendor Wrappers

Many designs need to connect Livt code to vendor-specific primitives: PLLs, block RAMs, transceivers, IO buffers, clocking resources, or vendor IP.

The usual strategy is to wrap vendor-specific functionality behind a stable Livt interface:

interface IUartPins
{
    rx: in logic
    tx: out logic
}

The Livt design depends on the interface. The vendor-specific wrapper handles the details of the target device.

Constraints and Timing

Livt source does not replace timing constraints. Vendor flows still need clock definitions, pin assignments, IO standards, derived clocks, false paths, and other constraints.

Keep constraints versioned with the project. When a Livt interface or top-level port changes, check whether constraints must change too.

Inspecting Top-Level Ports

Before integrating into a vendor project, inspect the top-level ports:

• Are input and output directions correct?
• Are clock and reset ports named and connected as expected?
• Are interface signals grouped and named in a way the board-level design can review?
• Are public stored fields exposed intentionally?
• Are test-only components excluded from synthesis?

This inspection catches boundary mistakes early.

Deployment Considerations

Deployment is project-specific, but the pattern is consistent:

• build Livt
• run tests
• collect build artifacts
• create or update the vendor project
• run vendor synthesis and implementation
• archive reports and bitstreams

As the design matures, automate these steps in CI so hardware integration is repeatable.

Summary

Livt should fit into existing hardware flows, not replace them all at once. Keep build artifacts visible, maintain clean top-level boundaries, wrap vendor-specific blocks behind interfaces, use .livt/vendor for vendor workspace output, and treat constraints as part of the design.