Skip to content

Commit

Permalink
Add legacy tool API docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@olofk
olofk committed Nov 18, 2023
1 parent de84ee5 commit c9e0e98
Show file tree
Hide file tree
Showing 3 changed files with 94 additions and 266 deletions.
8 changes: 7 additions & 1 deletion doc/conf.py
View file
Expand Up @@ -67,7 +67,7 @@
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
language = "en"

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
Expand Down Expand Up @@ -207,3 +207,9 @@

# Take class documentation from both __init__(), and the class docstring.
autoclass_content = "both"

from edalize.edatool import gen_tool_docs

s = gen_tool_docs()
with open(os.path.join(os.path.abspath("."), "edam/tools.rst"), "w") as f:
f.write(s)
291 changes: 26 additions & 265 deletions doc/edam/api.rst
View file
Expand Up @@ -8,16 +8,39 @@ Most keys are optional. The ones which are required are marked accordingly
============ ===================== ===========
Field Name Type Description
============ ===================== ===========
dependencies Dict of `Dependency`_ Direct dependencies of each core that is contained in the EDAM.
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.
tool_options `Tool Options`_ A dictionary of tool-specific options. Used by the legacy Tool API
toplevel List of String Toplevel module(s) for the project.
version String EDAM Version of the file.
vpi List of `VPI`_ VPI modules to build for the project.
============ ===================== ===========

Dependency
----------

An EDAM description is typically composed from multiple cores that have been combined to a larger project. In some cases it can be useful for Edalize flows or tools to be aware of the relation between these cores so that they can recreate the dependency tree. Each Dependency entry contains a list of other cores on which it has a direct dependency.

Example dict of Dependency entries where ::corescore:0 is the toplevel core which depends on ::servant:1.0.0, ::serving:1.0 and ::verilog-axis:0-r2. Both servant and serving in turn depend on serv:

.. code:: yaml
dependencies:
::corescore:0:
- ::servant:1.0.0
- ::serving:0
- ::verilog-axis:0-r2
::serv:1.0.0-r1: []
::servant:1.0.0:
- ::serv:1.0.0-r1
::serving:0:
- ::serv:1.0.0-r1
::verilog-axis:0-r2: []
File
----
Expand Down Expand Up @@ -95,270 +118,7 @@ paramtype String **Required** Type of parameter. Valid valu
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 (**S**\ kywater **O**\ pen-source **F**\ PG\ **A**) IPs:

- ``OPENFPGA_PATH``: directory of the `OpenFPGA framework <https://github.com/lnis-uofu/OpenFPGA>`_ Github repo (`documentation <https://openfpga.readthedocs.io/>`_)
- ``SOFA_PATH``: directory of the `SOFA <https://github.com/lnis-uofu/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 ``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``.

.. code-block:: python
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
.. include:: tools.rst

VPI
---
Expand All @@ -373,3 +133,4 @@ libs List of String Extra libraries
name String Name of VPI library
src_files List of String Source files for VPI library
================ ===================== ===========

0 comments on commit c9e0e98

Please sign in to comment.