fusesoc 2.2.1__tar.gz → 2.4__tar.gz

{fusesoc-2.2.1 → fusesoc-2.4}/.github/workflows/ci.yml

@@ -23,21 +23,28 @@ jobs:
         # https://github.com/olofk/fusesoc/issues/528
         #- { icon: 🧊, name: windows-latest }
         pyver:
-          - '3.6'
           - '3.7'
           - '3.8'
           - '3.9'
           - '3.10'
-          - '3.11.0-alpha - 3.11.0'
+          - '3.11'
+          - '3.12'
+        exclude:
+          #Fails because github can't find an arm64 image for Python 3.7???
+          - os: {name: macos-latest}
+            pyver: '3.7'
+          #Fails because one test expects a different output during an exception
+          - os: {name: macos-latest}
+            pyver: '3.8'
     runs-on: ${{ matrix.os.name }}
     name: ${{ matrix.os.icon }} ${{ matrix.os.name }} | ${{ matrix.pyver }}
     steps:
 
     - name: 🧰 Repository Checkout
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
 
     - name: 🐍 Set up Python ${{ matrix.pyver }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.pyver }}
 

{fusesoc-2.2.1 → fusesoc-2.4}/.github/workflows/lint.yml

@@ -9,6 +9,6 @@ jobs:
   pre-commit:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
-    - uses: actions/setup-python@v2
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
     - uses: pre-commit/action@v2.0.0

{fusesoc-2.2.1 → fusesoc-2.4}/.pre-commit-config.yaml

@@ -10,6 +10,7 @@ repos:
       - id: check-docstring-first
       - id: requirements-txt-fixer
       - id: check-yaml
+        exclude: ^tests/capi2_cores/misc/syntax_error\.core$
         types: [file]
         files: ^tests/capi2_cores/.+\.core$
       - id: end-of-file-fixer

{fusesoc-2.2.1 → fusesoc-2.4}/.readthedocs.yml

@@ -11,8 +11,15 @@ formats: all
 
 # Optionally set the version of Python and requirements required to build your docs
 python:
-  version: 3
   install:
     - requirements: doc/requirements.txt
     - method: pip
       path: .
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.11"
+  jobs:
+    post_checkout:
+      - git fetch --unshallow  || true

{fusesoc-2.2.1 → fusesoc-2.4}/NEWS

@@ -1,3 +1,41 @@
+2.4 2024-10-02 Olof Kindgren <olof.kindgren@gmail.com>
+======================================================
+* Add conflict handling for virtual cores
+* Connect generated cores in EDAM dependency graph
+* Support implicit name in library add command
+* Migrate from setup.py to pyproject.toml
+* Add support for EDAM filter plugins
+
+Contributors:
+Alexander Williams <awill@opentitan.org>
+Alfred E Neuman <quinky@gmx.ch>
+Daniel Copley <djcopley@users.noreply.github.com>
+Jelle van der Waa <jelle@vdwaa.nl>
+Olof Kindgren <olof.kindgren@gmail.com>
+Phillipe Jean-Jumeau <pljeanjumeau@gmail.com>
+
+2.3 2023-11-17 Olof Kindgren <olof.kindgren@gmail.com>
+======================================================
+* Add CLI to read/write config settings
+* Separate CLI from library to ease integration
+* Add --work-root to directly set output dir
+* Show core filename with "fusesoc core show"
+* Allow matching against only "name" component in VLNV
+* Improve inheritance rules between targets
+* Warn on duplicate cores
+* Support prepend keyword for generators
+* Reenable Windows tests
+* + improved error handling, bug fixes and refactoring
+
+Contributors:
+Benjamin Hallenrud <Benjamin.hallenrud@gmail.com>
+Erik Waling <erik.waling@gmail.com>
+Ethan Sifferman <ethan@sifferman.dev>
+Mykyta Haranko <mykyta.haranko@gmail.com>
+Olof Kindgren <olof.kindgren@gmail.com>
+Shareef Jalloq <shareef.jalloq@idexbiometrics.com>
+William D. Jones <thor0505@comcast.net>
+
 2.2 2023-04-18 Olof Kindgren <olof.kindgren@gmail.com>
 ======================================================
 * Use jsonschema to describe and validate CAPI2 files

{fusesoc-2.2.1 → fusesoc-2.4}/PKG-INFO

@@ -1,25 +1,33 @@
 Metadata-Version: 2.1
 Name: fusesoc
-Version: 2.2.1
-Summary: FuseSoC is a package manager and a set of build tools for HDL (Hardware Description Language) code.
-Home-page: https://github.com/olofk/fusesoc
-Author: Olof Kindgren
-Author-email: olof.kindgren@gmail.com
-License: BSD-2-Clause
-Keywords: VHDL,verilog,hdl,rtl,synthesis,FPGA,simulation,Xilinx,Altera
+Version: 2.4
+Summary: Award-winnning package manager and build abstraction tool for HDL code
+Author-email: Olof Kindgren <olof@award-winning.me>
+Maintainer-email: Olof Kindgren <olof@award-winning.me>
+Project-URL: Homepage, https://fusesoc.net
+Project-URL: Documentation, https://fusesoc.readthedocs.io
+Project-URL: Repository, https://github.com/olofk/fusesoc
+Project-URL: Issues, https://github.com/olofk/fusesoc/issues
+Project-URL: Changelog, https://github.com/olofk/fusesoc/blob/main/NEWS
+Keywords: VHDL,verilog,hdl,rtl,synthesis,FPGA,simulation,ASIC
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Topic :: Utilities
 Classifier: Topic :: Software Development :: Build Tools
 Classifier: License :: OSI Approved :: BSD License
-Requires-Python: >=3.6, <4
+Requires-Python: <4,>=3.6
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: edalize>=0.4.1
+Requires-Dist: pyparsing>=2.3.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: simplesat>=0.8.0
+Requires-Dist: fastjsonschema
+Requires-Dist: jsonschema2md
 
 # FuseSoC
 
 [![CI status](https://github.com/olofk/fusesoc/workflows/CI/badge.svg)](https://github.com/olofk/fusesoc/actions?query=workflow%3ACI)
 [![image](https://img.shields.io/pypi/dm/fusesoc.svg?label=PyPI%20downloads)](https://pypi.org/project/fusesoc/)
-[![LibreCores](https://www.librecores.org/olofk/FuseSoC/badge.svg?style=flat)](https://www.librecores.org/olofk/FuseSoC)
 
 ## Introduction
 

{fusesoc-2.2.1 → fusesoc-2.4}/README.md

@@ -2,7 +2,6 @@
 
 [![CI status](https://github.com/olofk/fusesoc/workflows/CI/badge.svg)](https://github.com/olofk/fusesoc/actions?query=workflow%3ACI)
 [![image](https://img.shields.io/pypi/dm/fusesoc.svg?label=PyPI%20downloads)](https://pypi.org/project/fusesoc/)
-[![LibreCores](https://www.librecores.org/olofk/FuseSoC/badge.svg?style=flat)](https://www.librecores.org/olofk/FuseSoC)
 
 ## Introduction
 

fusesoc-2.4/doc/requirements.txt

@@ -0,0 +1,4 @@
+myst_parser >= 0.18.0
+Sphinx >= 6.2.1
+sphinx-rtd-theme >= 1.2.0
+sphinxcontrib-programoutput

{fusesoc-2.2.1 → fusesoc-2.4}/doc/source/conf.py

@@ -14,8 +14,11 @@ import sys
 from datetime import datetime
 from distutils.version import LooseVersion
 
+import jsonschema2md
+
 import fusesoc
-from fusesoc.capi2.core import gen_doc
+from fusesoc.capi2.json_schema import capi2_schema
+from fusesoc.utils import yaml_read
 
 # -- Path setup --------------------------------------------------------------
 
@@ -33,7 +36,12 @@ copyright = f"2018-{datetime.now().year}, Olof Kindgren"
 author = "Olof Kindgren"
 
 # The full version, including alpha/beta/rc tags.
-release = fusesoc.__version__
+try:
+    from fusesoc.version import version as __version__
+except ImportError:
+    __version__ = "unknown"
+
+release = __version__
 # The short X.Y version.
 v_major, v_minor = LooseVersion(release).version[:2]
 version = f"{v_major}.{v_minor}"
@@ -56,6 +64,7 @@ extensions = [
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinxcontrib.programoutput",
+    "myst_parser",
 ]
 
 intersphinx_mapping = {"https://docs.python.org/3": None}
@@ -67,8 +76,7 @@ templates_path = ["_templates"]
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-# source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = [".rst", ".md"]
 
 # The master toctree document.
 master_doc = "index"
@@ -203,7 +211,11 @@ texinfo_documents = [
 
 # -- Extension configuration -------------------------------------------------
 
+p = jsonschema2md.Parser(
+    examples_as_yaml=False,
+    show_examples="all",
+)
+md_lines = p.parse_schema(yaml_read(capi2_schema))
 
-s = gen_doc()
-with open(os.path.join(os.path.abspath("."), "ref/capi2.rst"), "w") as f:
-    f.write(s)
+with open(os.path.join(os.path.abspath("."), "ref/capi2.md"), "w") as f:
+    f.write("".join(md_lines))

{fusesoc-2.2.1 → fusesoc-2.4}/doc/source/ref/index.rst

@@ -6,6 +6,6 @@ FuseSoC Reference Manual
    :maxdepth: 2
    :caption: Contents
 
-   capi2.rst
+   capi2.md
    migrations.rst
    glossary.rst

fusesoc-2.4/doc/source/user/build_system/filters.rst

@@ -0,0 +1,99 @@
+.. _ug_build_system_filters:
+
+Filters: Make system-wide modifications to the EDAM structure
+=============================================================
+
+The last thing FuseSoC does before handing over to Edalize, is to prepare an EDAM file containing a description of the complete system and everything that the EDA tools need to know. It is sometimes useful to make system-wide changes after the system is assembled, and this is where filters come in. Filters are additional tasks that can be run to analyze and modify the EDAM structure, and through that structure the filters have access to the complete dependency tree and all source files.
+
+FuseSoC ships with a few built-in filters for generally useful tasks:
+
+* autotype: Sets file types according to the file name prefix for files that don't have an explicit file type set.
+* custom: Runs the command specified with the environment variable `FUSESOC_CUSTOM_FILTER`. Two arguments are passed to the command. The first specifies the EDAM (yaml) file the custom command is supposed to read. The second specifies the name of the file that the filter should use to return the modified EDAM struct.
+* dot: Creates a GraphViz dot file of the dependency tree
+
+All filters are run from the work root directory.
+
+.. note::
+    Technically, an Edalize frontend can perform the exact same task as a FuseSoC EDAM filter. The difference is more philosophical in that a filter can be seen as something that fixes up the system before it is ready to be consumed by an EDA tool, while an Edalize frontend typically *is* an EDA tool. The filters will also possibly have access to more FuseSoC internals in the future.
+
+Using filters
+-------------
+
+There are three way to enable which filters to be applied. These three options have various use-cases.
+
+Filters in targets
+~~~~~~~~~~~~~~~~~~
+
+Filters specified in a target section of a core are typically required for the the build to work. In order to enable a filter for a target, add a list of filters using the `filters` key.
+
+.. code-block:: yaml
+
+   # An excerpt from a core file.
+   targets:
+     sim:
+       # ...
+       filters: [autotype, dot] # Apply the autotype and dot filters in that order
+
+Filters in the configuration file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Filters can be set in the configuration file as a list of space-separated strings in the `main` section. These can be set with the fusesoc config cli, e.g. `fusesoc config filters "filter1 filter2"`. Filters set in the config file are typically used when all targets of the cores in the workspace need some filter to be applied, or just as a convenienence for users who like to have som particular filter always enabled. These filters are applied after the ones from the core file targets.
+
+Filters on the command-line
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is also possible to set filters on the command-line. This is typically used for one-off filters, e.g. to generate some debug info. They are enabled with the `--filter` parameters, e.g. `fusesoc run --filter=dot --target=sim ...`. The `--filter` parameter can be specified multiple times to add more filters. Filters on the command-line are applied after the ones from the configuration file.
+
+
+Creating additional filters
+---------------------------
+
+A filter is a Python module that contains a class with the same name as the module, but capitalized. The class needs to implement a function called `run` which takes the EDAM struct as the first argumen and the work root as the second argument. The function needs to return the new EDAM struct even if it is unmodified.
+
+Filter template::
+
+    import logging
+    import os
+
+    logger = logging.getLogger(__name__)
+
+
+    class Customfilter:
+        def run(self, edam, work_root):
+            # Print file sizes of all verilog files in the system
+            for f in edam["files"]:
+                if f["file_type"].startswith("verilogSource"):
+                    size = os.path.getsize(os.path.join(work_root, f["name"]))
+                    print(f"{f['name']} is {size} bytes")
+
+            # Add an additional parameter
+            edam["parameters"]["my_number"] = {"datatype" : "int",
+                                               "paramtype": "vlogdefine",
+                                               "default" : 5446}
+
+            # Change the system name
+            edam["name"] = "bestsystemever"
+
+            # Return modified EDAM struct
+            return edam
+
+FuseSoC implements support for implicit namespace packages (https://peps.python.org/pep-0420/) This means that subclasses that logically belong to FuseSoC can be distributed over several physical locations and is something we can take advantage of to add new filters outside of the FuseSoC code base.
+
+In order to do that we will create a directory structure that mirrors the structure of FuseSoC like the example below::
+
+  externalplugin/
+      fusesoc/
+          filters/
+	      customfilter.py
+	      anothercustomfilter.py
+
+There are two common options for making the above `customfilter.py` and `anothercustomfilter.py` available to FuseSoC.
+
+The first way is to add the `externalplugin` path to ``PYTHONPATH``. The other is to add a `setup.py` in the `externalplugin` directory and install the filter plugin with pip as with other Python packages.
+
+A `setup.py` in its absolutely most minimal form is listed below and is enough to install the plugin as a package in development mode using ``pip install --user -e .`` from the `externalplugin` directory.::
+
+  from setuptools import setup
+  setup()
+
+A real `setup.py` like the one used by FuseSoC normally contains a lot more information.

{fusesoc-2.2.1 → fusesoc-2.4}/doc/source/user/build_system/index.rst

@@ -35,6 +35,7 @@ A full reference documentation on the CAPI2 core file format can be found in the
    core_files.rst
    eda_flows.rst
    dependencies.rst
+   filters.rst
    flags.rst
    generators.rst
    hooks.rst

fusesoc-2.4/doc/source/user/knowledgebase.rst

@@ -0,0 +1,119 @@
+*****************************
+Common Problems and Solutions
+*****************************
+
+Making changes to cores in a library
+====================================
+
+A common situation is that a user wants to use their own copy of a core,
+instead of the one provided by a library, for example to fix a bug or
+add new functionality. The following steps can be used to achieve this:
+
+**Example.** Replace a core in a library with a user-specified version
+
+#. Create a new directory to keep the user-copies of the cores (this
+   directory will be referred to as ``$corelib`` from now on)
+#. Download the core source (the repository or URL can be found in the
+   ``[provider]`` section of the original core)
+#. *If the downloaded core already contains a .core file, this step is
+   ignored* Copy the original .core file to the root of the downloaded
+   core. Edit the file and remove the ``[provider]`` section. (This will
+   stop FuseSoC from downloading the core and use files from the
+   directory containing the .core file instead)
+#. Add ``$corelib`` to the end of your library search path, either by
+   editing ``fusesoc.conf`` or by adding ``--cores-root=$corelib`` to
+   the command-line arguments
+#. Verify that the new core is found by running fusesoc core-info $core. Check
+   the output to see that “Core root:” is set to the directory where the core
+   was downloaded
+
+Dependency tree for a core with optional components
+===================================================
+
+Many cores have a part that is only used in some flows. This could for example be a BFM, VIP or some kind of behavioral model that is only used in simulation flows. Or it could be timing constraints for synthesis. As long as these are only by the core itself, it's easiest to put them into different filesets and let each simulation or synthesis target pick the right subset of filesets.
+
+A more complicated situation arises when a user uses this core as a dependency and wants to have different filesets for different flows in the toplevel core. In this case, it is typically better to split out the optional part into its own cores and have the toplevel filesets depend on the different cores.
+
+**Example** Let's assume a core (comp) comes with a BFM. We want to use the BFM when doing block-level simulations of the core and when doing full system simulations which uses this core. We don't want to have the BFM present when doing full system synthesis. The most general solution is to split out the BFM to a separate core file. The following example shows a setup with a component (comp.core) that has a BFM (comp_bfm.core) which is used inside a larger system (top.core). The component has a testbench target (sim) and the larger system has two testbenches (tb1 and tb2) which both uses the BFM and the component. The larger system can also be synthesized without the BFM.
+
+.. image:: optional_deps.png
+  :alt: Alternative text
+
+.. code-block:: yaml
+   :caption: comp_bfm.core
+
+    CAPI=2:
+
+    name : ::comp_bfm:0
+
+    filesets:
+      bfm:
+        files: {comp_bfm.sv : {file_type : systemVerilogSource}}
+
+    targets:
+      default:
+        filesets : [bfm]
+
+.. code-block:: yaml
+   :caption: comp.core
+
+    CAPI=2:
+
+    name : ::comp:0
+
+    filesets:
+      rtl:
+        files: {comp.sv : {file_type : systemVerilogSource}}
+
+      tb_files:
+        files: {comp_tb.sv : {file_type : systemVerilogSource}}
+        depend: [comp_bfm]
+
+    targets:
+      default:
+        filesets : [rtl]
+
+      sim:
+        filesets : [rtl, tb_files]
+
+.. code-block:: yaml
+   :caption: top.core
+
+    CAPI=2:
+
+    name : ::top:0
+
+    filesets:
+      rtl:
+        files: {top.sv : {file_type : systemVerilogSource}}
+        depend: [comp]
+
+      tb_common:
+        files: {tb_common.sv : {file_type : systemVerilogSource}}
+        depend: [comp_bfm]
+
+      tb1_files:
+        files: {tb1.sv : {file_type : systemVerilogSource}}
+
+      tb2_files:
+        files: {tb1.sv : {file_type : systemVerilogSource}}
+
+      synth_files:
+        files: {constraints.sdc : {file_type : SDC}}
+
+    targets:
+      sim: &sim
+        filesets : [rtl, tb_files]
+
+      tb1:
+        <<: *sim
+        filesets_append : [tb1_files]
+
+      tb2:
+        <<: *sim
+        filesets_append : [tb2_files]
+
+      synth:
+        filesets : [rtl, synth_files]
+
+An alternative solution to the above, is to use flags, as described in :ref:`ug_build_system_flags`, where the inclusion of the optional files are controlled by flags. These flags can be assigned default values in the top level targets for convenience.

{fusesoc-2.2.1 → fusesoc-2.4}/fusesoc/capi2/core.py

@@ -13,7 +13,7 @@ from filecmp import cmp
 
 from fusesoc import utils
 from fusesoc.capi2.coredata import CoreData
-from fusesoc.provider import get_provider
+from fusesoc.provider.provider import get_provider
 from fusesoc.vlnv import Vlnv
 
 logger = logging.getLogger(__name__)
@@ -33,8 +33,7 @@ class Core:
 
         self.cache_root = cache_root
 
-        basename = os.path.basename(self.core_file)
-
+        self.core_basename = os.path.basename(self.core_file)
         self.core_root = os.path.dirname(self.core_file)
 
         # Populated by CoreDB._solve(). TODO: Find a better solution for that.
@@ -107,7 +106,6 @@ class Core:
                     FutureWarning,
                 )
             if not os.path.isabs(f):
-
                 if os.path.exists(os.path.join(self.core_root, f)):
                     src = os.path.join(self.core_root, f)
                 elif os.path.exists(os.path.join(self.files_root, f)):
@@ -130,7 +128,7 @@ class Core:
         for root, dirs, files in os.walk(dst_dir):
             for f in files:
                 _abs_f = os.path.join(root, f)
-                if not os.path.relpath(_abs_f, dst_dir) in src_files:
+                if not os.path.relpath(_abs_f, dst_dir).replace("\\", "/") in src_files:
                     os.remove(_abs_f)
 
     def _get_script_names(self, flags):
@@ -174,8 +172,14 @@ class Core:
                     # Special case for tool as we get it from default_tool
                     flags["tool"] = str(target["default_tool"])
 
+        else:
+            raise RuntimeError(f"'{self.name}' has no target '{target_name}'")
         return flags
 
+    def get_filters(self, flags):
+        target_name, target = self._get_target(flags)
+        return target.get("filters", [])
+
     def get_flow(self, flags):
         self._debug("Getting flow for flags {}".format(str(flags)))
         flow = None
@@ -516,6 +520,7 @@ class Core:
 Name:        {}
 Description: {}
 Core root:   {}
+Core file:   {}
 
 Targets:
 {}"""
@@ -539,6 +544,7 @@ Targets:
             str(self.name),
             str(self.get_description() or "<No description>"),
             str(self.core_root),
+            str(self.core_basename),
             targets,
         )
 

fusesoc-2.4/fusesoc/capi2/inheritance.py

@@ -0,0 +1,39 @@
+# Copyright FuseSoC contributors
+# Licensed under the 2-Clause BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-2-Clause
+
+import copy
+import re
+
+from fusesoc import utils
+
+
+class Inheritance:
+    MERGE_OPERATOR = "<<__FUSESOC_MERGE_OVERLOAD__<<"
+
+    def yaml_merge_2_fusesoc_merge(capi):
+        """
+        Replace YAML merge key operator (<<) with FuseSoC merge operator
+        """
+        yaml_merge_pattern = (
+            r"((?:\n|{|\{\s*(?:[^{}]*\{[^{}]*\})*[^{}]*\},)\s*)<<(?=\s*:)"
+        )
+        while re.search(yaml_merge_pattern, capi):
+            capi = re.sub(yaml_merge_pattern, r"\1" + Inheritance.MERGE_OPERATOR, capi)
+        return capi
+
+    def elaborate_inheritance(capi):
+        if not isinstance(capi, dict):
+            return capi
+
+        for key, value in capi.items():
+            if isinstance(value, dict):
+                capi[key] = Inheritance.elaborate_inheritance(copy.deepcopy(value))
+
+        parent = capi.pop(Inheritance.MERGE_OPERATOR, {})
+        if isinstance(parent, dict):
+            capi = utils.merge_dict(parent, capi, concat_list_appends_only=True)
+        else:
+            raise SyntaxError("Invalid use of inheritance operator")
+
+        return capi

{fusesoc-2.2.1 → fusesoc-2.4}/fusesoc/capi2/json_schema.py

@@ -110,7 +110,7 @@ capi2_schema = """
           "additionalProperties": false,
           "required": [
             "name",
-            "repo",
+            "repo"
           ]
         },
         {
@@ -272,7 +272,7 @@ capi2_schema = """
               }
             }
           },
-          "additionalProperties": false,
+          "additionalProperties": false
         }
       },
       "additionalProperties": false
@@ -289,9 +289,9 @@ capi2_schema = """
               "type": "string"
             },
             "position": {
-              "description": "Where to insert the generated core. Legal values are *first*, *append* or *last*. *append* will insert core after the core that called the generator",
+              "description": "Where to insert the generated core. Legal values are *first*, *prepend*, *append* or *last*. *prepend* (*append*) will insert core before (after) the core that called the generator",
               "type": "string",
-              "pattern": "^first|append|last$"
+              "pattern": "^first|prepend|append|last$"
             },
             "parameters": {
               "description": "Generator-specific parameters. ``fusesoc gen show $generator`` might show available parameters. ",
@@ -317,7 +317,7 @@ capi2_schema = """
               "type": "string"
             },
             "interpreter": {
-              "description": "If the command needs a custom interpreter (such as python) this will be inserted as the first argument before command when calling the generator. The interpreter needs to be on the system PATH.",
+              "description": "If the command needs a custom interpreter (such as python) this will be inserted as the first argument before command when calling the generator. The interpreter needs to be on the system PATH; specifically, shutil.which needs to be able to find the interpreter).",
               "type": "string"
             },
             "cache_type": {
@@ -375,7 +375,7 @@ capi2_schema = """
               }
             }
           },
-          "additionalProperties": false,
+          "additionalProperties": false
         }
       }
     },
@@ -386,7 +386,7 @@ capi2_schema = """
         "^.+$": {
           "patternProperties": {
             "^default_tool$": {
-              "description": "Default tool to use unless overridden with ``--tool=``",
+              "description": "Default tool to use unless overridden with ``--tool=`` This key is used by the Edalize Tool API and is ignored if the Flow API is used instead.",
               "type": "string"
             },
             "^description$": {
@@ -394,11 +394,11 @@ capi2_schema = """
               "type": "string"
             },
             "^flow$": {
-              "description": "Edalize backend flow to use for target",
+              "description": "Edalize backend flow to use for target. Setting this key enables the flow API instead of the legacy Tool API.",
               "type": "string"
             },
             "^flow_options$": {
-              "description": "Tool- and flow-specific options",
+              "description": "Tool- and flow-specific options. Used by the Flow API. The Edalize documentation contains information on available options for different flows (https://edalize.readthedocs.io/en/latest/edam/api.html#flow-options)",
               "type": "object",
               "patternProperties": {
                 "^.+$": {
@@ -458,7 +458,7 @@ capi2_schema = """
               "additionalProperties": false
             },
             "^tools$": {
-              "description": "Tool-specific options for target",
+              "description": "Tool-specific options for target. Used by the legacy Tool API. The contents of this section is handled by Edalize, and a list of available tool options for each tool can be found in the Edalize documentation (https://edalize.readthedocs.io/en/latest/edam/api.html#tool-options)",
               "type": "object",
               "patternProperties": {
                 "^.+$": {
@@ -508,6 +508,13 @@ capi2_schema = """
                 "type": "string"
               }
             },
+            "^filters(_append)?$": {
+              "description": "EDAM filters to apply",
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
             "^generate(_append)?$": {
               "description": "Parameterized generators to run for this target with optional parametrization",
               "type": "array",