diff --git a/doc/conf.py b/doc/conf.py index 249f91491..ab19c81d6 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -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. @@ -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) diff --git a/doc/edam/api.rst b/doc/edam/api.rst index bb945dfc8..b6be0ba79 100644 --- a/doc/edam/api.rst +++ b/doc/edam/api.rst @@ -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 ---- @@ -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 `_ 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 ``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 --- @@ -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 ================ ===================== =========== + diff --git a/edalize/edatool.py b/edalize/edatool.py index f53f31107..e865a0c90 100644 --- a/edalize/edatool.py +++ b/edalize/edatool.py @@ -524,3 +524,64 @@ def _write_fileset_to_f_file( unused_files.append(src_file) return unused_files + + +def _class_doc(items): + s = items["description"] + "\n\n" + lines = [] + name_len = 10 + type_len = 4 + for item in items.get("members", []): + name_len = max(name_len, len(item["name"])) + type_len = max(type_len, len(item["type"])) + lines.append((item["name"], item["type"], item["desc"])) + for item in items.get("dicts", []): + name_len = max(name_len, len(item["name"])) + type_len = max(type_len, len(item["type"]) + 8) + lines.append((item["name"], "Dict of {}".format(item["type"]), item["desc"])) + for item in items.get("lists", {}): + name_len = max(name_len, len(item["name"])) + type_len = max(type_len, len(item["type"]) + 8) + lines.append((item["name"], "List of {}".format(item["type"]), item["desc"])) + + s += "=" * name_len + " " + "=" * type_len + " " + "=" * 11 + "\n" + s += "Field Name".ljust(name_len + 1) + "Type".ljust(type_len + 1) + "Description\n" + s += "=" * name_len + " " + "=" * type_len + " " + "=" * 11 + "\n" + for line in lines: + s += line[0].ljust(name_len + 1) + s += line[1].ljust(type_len + 1) + s += line[2] + s += "\n" + s += "=" * name_len + " " + "=" * type_len + " " + "=" * 11 + "\n" + return s + + +def gen_tool_docs(): + table = [] + s = "" + for backend in get_edatools(): + name = backend.__name__ + + if name == "Edatool": + continue + + table.append( + { + "name": name.lower(), + "type": "`" + name + "`_", + "desc": name + "-specific options", + } + ) + + s += "\n{}\n{}\n\n".format(name, "~" * len(name)) + s += _class_doc(backend.get_doc(0)) + + return ( + _class_doc( + { + "description": "Tool options are used to set tool-specific options. Each key corresponds to a specific EDA tool.\n\n**Note** This section is only used by the legacy Tool API", + "members": table, + } + ) + + s + )