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 |
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 |
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:
OPENFPGA_PATH
: directory of the OpenFPGA framework Github repo (documentation)SOFA_PATH
: directory of the SOFA eFPGA IPs Github repo
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 |
|
Selected methodology |
goals |
List of String |
|
Selected goals |
rule_parameters |
List of String |
|
Options passed with |
spyglass_parameters |
List of String |
|
Rule parameters passed with |
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 |
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 |
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 |