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
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

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

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

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