EDA Metadata

The EDAM (EDA Metadata) API is a data structure with the intention to describe all input parameters that an EDA tool will need to run synthesis or build a simulation model from a set of HDL files. The data described in EDAM is tool-agnostic, with the option to supply tool-specific parameters when required. The data structure itself is a tree structure with lists and dictionaries using simple data types as strings and integers for the actual values, and is suitable for (de)serialization with YAML or JSON.

Most keys are optional. The ones which are required are marked accordingly

Field Name

Type

Description

files

List of File

Contains all the HDL source files, constraint files, vendor IP description files, memory initialization files etc. for the project.

hooks

Hook

A dictionary of extra commands to execute at various stages of the project build/run.

name

String

Required Name of the project

parameters

Dict of Parameter

Specifies build- and run-time parameters, such as plusargs, VHDL generics, Verilog defines etc.

tool_options

Tool Options

A dictionary of tool-specific options.

toplevel

List of String

Toplevel module(s) for the project.

vpi

List of VPI

VPI modules to build for the project.

File

A file has a name, which is the absolute path or the relative path to the working directory. It also has a type, which describes the intended usage of the file. Different EDA tools handle different subsets of files and are expected to ignore files that are not applicable to them, but might issue a warning. By specifying user as the file type, the backends will explicitly ignore the file. The valid file types are based on the IP-XACT 2014 standard, with some additional file types added. The file types not covered by IP-XACT are listed below

  • QIP : Intel Quartus IP file

  • UCF : Xilinx ISE constraint file

  • verilogSource-2005 : Verilog 200 source

  • vhdlSource-2008 : VHDL 2008 source

  • xci : Xilinx Vivado IP file

  • xdc : Xilinx Vivado constraint file

Field Name

Type

Description

name

String

Required File name with (absolute or relative) path

file_type

String

Required File type

is_include_file

Bool

Indicates if this file should be treated as an include file (default false)

include_path

String

When is_include_file is true, the directory containing the file will be added to the include path. include_path allows setting an explicit directory to use instead

logical_name

String

Logical name (e.g. VHDL/SystemVerilog library) of the file

Hook

Hooks are scripts that can be registered to execute during various phases of Edalize. The Hook structure contains a key for each of the four defined stages, and the value of each key is a list of Script to be executed.

The four defined stages are

Key

Description

pre_build

Executed before calling build

post_build

Executed after calling build

pre_run

Executed before calling run

post_run

Executed after calling run

Script

Field Name

Type

Description

cmd

List of String

Command to execute

env

Dict of String

Additional environment variables to set before launching script

name

String

User-friendly name of the script

Parameter

A parameter is used for build- and run-time parameters, such as Verilog plusargs, VHDL generics, Verilog defines, Verilog parameters or any extra command-line options that should be sent to the simulation model. Different tools support different subsets of parameters. The list below describes valid parameter types

  • cmdlinearg : Command-line argument to be sent to a running simulation model

  • generic : VHDL generic to be set at elaboration-time

  • plusarg : Verilog plusarg to be set at run-time

  • vlogdefine : Verilog define to be set at compile-time

  • vlogparam : Verilog toplevel parameter to be set at compile-time

Field Name

Type

Description

datatype

String

Required Data type of the parameter. Valid values are bool, file, int, str. file is similar to str, but the value is treated as a path and converted to an absolute path

default

Specified by datatype

Default value to use if user does not provide a value during the configure or run stages

description

String

User-friendly description of the parameter

paramtype

String

Required Type of parameter. Valid values are cmdlinearg, generic, plusarg, vlogparam, vlogdefine

Tool options

Tool options are used to set tool-specific options. Each key corresponds to a specific EDA tool.

Field Name

Type

Description

ghdl

String

Options for GHDL

icarus

String

Options for Icarus Verilog

icestorm

String

Options for Project IceStorm

ise

String

Options for Xilinx ISE

isim

String

Options for Xilinx iSim

modelsim

String

Options for Mentor ModelSim

openfpga

String

Options for OpenFPGA OpenFPGA

quartus

String

Options for Intel Quartus

rivierapro

String

Options for Aldec RivieraPro

spyglass

String

Options for Synposys SpyGlass

trellis

String

Options for Project Trellis

vcs

String

Options for Synopsys VCS

verilator

String

Options for Verilator

vivado

String

Options for Xilinx Vivado

vunit

String

Options for VUnit

xcelium

String

Options for Cadence Xcelium

xsim

String

Options for Xilinx XSim

ghdl

Field Name

Type

Description

analyze_options

List of String

Extra options used for the GHDL analyze stage (ghdl -a)

run_options

List of String

Extra options used when running GHDL simulations (ghdl -r)

icarus

Field Name

Type

Description

iverilog_options

List of String

Extra options for compilation with iverilog

timescale

String

Default (Verilog) timescale to use before user sets one explicitly

icestorm

Field Name

Type

Description

arachne_pnr_options

List of String

Options for ArachnePNR Place & Route

nextpnr_options

List of String

Options for NextPNR Place & Route

pnr

String

Select P&R tool. Valid values are arachne and next. Default is arachne

yosys_synth_options

List of String

Options for Yosys Synthesis

ise

Field Name

Type

Description

family

String

FPGA family e.g. spartan6, virtex5

device

String

Device identifier e.g. xc6slx45

package

String

Device package e.g. csg324

speed

String

Device speed grade e.g. -2

board_device_index

String

Specifies the FPGA’s device number in the JTAG chain, starting at 1.

isim

Field Name

Type

Description

fuse_options

List of String

Extra options for compilation with fuse

isim_options

List of String

Extra options for running compiled simulation model

modelsim

Field Name

Type

Description

vlog_options

List of String

Extra options for each Verilog file compiled with vlog

vsim_options

List of String

Extra options for running the simulation with vsim

openfpga

The following environment variables need to be sourced before running any simulation on SOFA (Skywater Open-source FPGA) IPs:

Field Name

Type

Description

arch

String

FPGA architecture e.g. sofa-hd, sofa-chd, sofa-qlhd and sofa-plus-hd

task_options

List of String

Extra options for running the task simulation with OpenFPGA framework (see the OpenFPGA documentation)

quartus

Field Name

Type

Description

board_device_index

List of String

Specifies the FPGA’s device number in the JTAG chain. The device index specifies the device where the flash programmer looks for the Nios® II JTAG debug module. JTAG devices are numbered relative to the JTAG chain, starting at 1. Use the tool jtagconfig to determine the index.

family

String

FPGA family e.g. Cyclone IV E

device

String

Device identifier. e.g. EP4CE55F23C8 or 5CSXFC6D6F31C8ES

quartus_options

List of String

Extra command-line options for Quartus

dse_options

List of String

Command-line options for Design Space Explorer

rivierapro

Field Name

Type

Description

vlog_options

List of String

Extra options for each Verilog file compiled with vlog

vsim_options

List of String

Extra options for running the simulation with vsim

spyglass

Field Name

Type

Default

Description

methodology

String

GuideWare/latest/block/rtl_handoff

Selected methodology

goals

List of String

[ 'lint/lint_rtl' ]

Selected goals

rule_parameters

List of String

[]

Options passed with set_option to Spyglass, e.g. “handlememory yes” to prevent error SYNTH_5273 on generic RAM descriptions

spyglass_parameters

List of String

[]

Rule parameters passed with set_parameter to Spyglass, e.g. handle_static_caselabels yes to allow localparam to be used in case labels (e.g. in state machines)

trellis

Field Name

Type

Description

nextpnr_options

List of String

Options for NextPNR Place & Route

yosys_synth_options

List of String

Options for Yosys Synthesis

vcs

Field Name

Type

Description

vcs_options

List of String

Compile time options passed to vcs

run_options

List of String

Runtime options passed to the simulation

verilator

Field Name

Type

Description

cli_parser

String

If cli_parser is set to managed, Edalize will parse all command-line options. Otherwise, they are sent directly to the compiled simulation model.

libs

List of String

Extra options to be passed as -LDFLAGS when linking the C++ testbench

mode

String

cc runs Verilator in regular C++ mode. sc runs in SystemC mode. lint-only only performs linting on the Verilog code

verilator_options

List of String

Extra options to be passed when verilating model

vivado

Field Name

Type

Description

part

String

Device identifier. e.g. xc7a35tcsg324-1

jobs

Integer

Number of jobs. Useful for parallelizing OOC (Out Of Context) syntheses.

vunit

Field Name

Type

Description

vunit_options

List of String

Extra options for the VUnit test runner

add_libraries

List of String

A list of framework libraries to add. Allowed values include “array_util”, “com”, “json4hdl”, “osvvm”, “random”, “verification_components”

vunit_runner

String

Name of the Python file exporting a VUnitRunner class (must derive from edalize.vunit_hooks.VUnitHooks) that is used to configure and execute test. This allows very customized test control via VUnit’s Python-interfaces.

In case a more advanced VUnit configuration or execution of the testbench is necessary, the option vunit_runner can be used to specify the filename of a Python script which can hook into the construction, parametrization, and execution of the test runner. For this to work, the Python script must export a class VUnitRunner(vunit_hooks.VUnitHooks) which derives from (and optionally overrides) the behavior of vunit_hooks.VUnitHooks.

from edalize.vunit_hooks import VUnitHooks
from vunit import VUnit
from vunit.ui import Library, Results
from typing import Mapping, Collection


class VUnitRunner(VUnitHooks):
    """Example of custom VUnit instrumentation."""

    def create(self) -> VUnit:
        """Customized creation of the test runner"""
        vu = VUnit.from_argv()
        vu.enable_check_preprocessing()
        return vu

    def handle_library(self, logical_name: str, vu_lib: Library):
        """Override this to customize each library, e.g. with additional simulator options.
        This hook will be invoked for each library, after all source files have been added.
        :param logical_name: The logical name of the library
        :param vu_lib: The vunit.ui.Library instance, configured with all sources of this `logical_name`
        """
        # e.g. you can access and customize test-bench entities of this library:
        if logical_name == "my_tb_library_name":
            entity = vu_lib.entity("my_toplevel_tb")
            entity.set_generic("message", "Test message")
            entity.add_config(name="TestConfig1",
                            generics=dict(CLK_FREQ=10000000))
            entity.add_config(name="TestConfig2",
                            generics=dict(CLK_FREQ=54687500))

    def main(self, vu: VUnit):
        """Override this for final parametrization of the :class:`VUnit` instance (after all libraries have been added),
        or for custom invocation of VUnit
        """
        def post_run_handler(results: Results):
            results.merge_coverage(file_name="coverage_data")

        vu.main(post_run=post_run_handler)

xcelium

Field Name

Type

Description

xmvlog_options

List of String

Extra options for compilation with xmvlog

xmvhdl_options

List of String

Extra options for compilation with xmvhdl

xmsim_options

List of String

Extra options for running simulation with with xsim

xrun_options

List of String

Extra options for invocation with with xrun

xsim

Field Name

Type

Description

xelab_options

List of String

Extra options for compilation with xelab

xsim_options

List of String

Extra options for running simulation with with xsim

toplevel

Name of the top level module/entity

VPI

Each Vpi object contains information on how to build the corresponding VPI library

Field Name

Type

Description

include_dirs

List of String

Extra include directories

libs

List of String

Extra libraries

name

String

Name of VPI library

src_files

List of String

Source files for VPI library