EDA API
=======

EDA 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 EDA API 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.

Root
----

files
~~~~~
A list of `File` objects. This list contains all the HDL source files for the project.

name
~~~~
Name of the project

parameters
~~~~~~~~~~
A list of `Parameter` objects. Specifies build- and run-time parameters, such as verilog plusargs, VHDL generics, verilog defines etc.

tool_options
~~~~~~~~~~~~
A dictionary of tool-specific options. Each key corresponds to a specific EDA tool. The following tools are standardized. The contents of each dictionary item is described in their own section.

ghdl
^^^^
analyze_options : String of extra options used for the GHDL analyze stage (`ghdl -a`)
run_options : String of extra options used when running GHDL simulations (`ghdl -r`)


icarus
^^^^^^
iverilog_options : String of extra options for compilation with `iverilog`

icestorm
^^^^^^^^
arachne_pnr_options : String of options for ArachnePNR Place & Route

ise
^^^
family : String value representing the FPGA family e.g. spartan6, virtex5
device : String value representing the device identifier e.g. xc6slx45
package : String value representing the device package e.g. csg324
speed  : String value representing the device speed grade e.g. -2

isim
^^^^
isim_options : String of extra options for compilation with `fuse`

modelsim
^^^^^^^^
vlog_options : String of options for each verilog file compiled with `vlog`
vsim_options : String of options to be used for invocations of simulation runs with `vsim`

quartus
^^^^^^^
family : String value representing the FPGA family e.g. "Cyclone IV E"
device : String value representing the device identifier. e.g. EP4CE55F23C8 or 5CSXFC6D6F31C8ES
quartus_options : String of extra command-line options for Quartus

rivierapro
^^^^^^^^^^
vlog_options : String of options for each verilog file compiled with `vlog`
vsim_options : String of options to be used for invocations of simulation runs with `vsim`

verilator
^^^^^^^^^
source_type : String defining the type of source used for the test bench (`C`, `CPP` or `systemC`
libs : String of extra libraries to be linked with the testbench FIXME -l ??
verilator_options : FIXME

vivado
^^^^^^
part : String value representing the device identifier. e.g. xc7a35tcsg324-1
hw_device : String value representing the device for programming. e.g. xc7a35t_0

xsim
^^^^
xsim_options : String of extra options for compilation with `xelab`

toplevel
~~~~~~~~
Name of the top level module/entity

vpi
~~~
List of `Vpi` objects. Each `Vpi` object contains information on how to build a given VPI library

File
----
name
~~~~
HDL source file with path (absolute or relative to EDA tool work directory)
file_type : String representing the type of the file. File types are a superset of IP-XACT file types. Valid file types not covered by the IP-XACT 2014 standard include:

- 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

is_include_file
~~~~~~~~~~~~~~~
Boolean (true/false) indicating if this file should be treated as an include file

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

Parameter
---------

datatype
~~~~~~~~
Specifies how the value of the parameter should be intepreted. Valid data types are `int`, `str`, `bool`, `file`

default
~~~~~~~
Optional default value of the parameter if the user does not specify a value

description
~~~~~~~~~~~
Textual description of the parameter

name
~~~~
Parameter name

paramtype
~~~~~~~~~
Parameter type. The following values are recognized

plusarg : Verilog plusarg to be set at run-time
vlogparam : Verilog toplevel parameter to be set at compile-time
generic : VHDL generic to be set at elaboration-time
cmdlinearg : Command-line argument to be sent to a running simulation model

vpi
---

name
~~~~
Name of the compiled VPI library

src_files
~~~~~~~~~
List of source files to be used for compiling the VPI library

include_dirs
~~~~~~~~~~~~
List of include directories to be used when compiling the VPI library

libs
~~~~
List of libraries to be linked with the VPI library
