fusesoc 2.3__tar.gz → 2.4.2__tar.gz

{fusesoc-2.3 → fusesoc-2.4.2}/.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@v3
+      uses: actions/checkout@v4
 
     - name: 🐍 Set up Python ${{ matrix.pyver }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.pyver }}
 

fusesoc-2.4.2/.github/workflows/lint.yml

@@ -0,0 +1,11 @@
+name: lint
+
+on: [pull_request, push]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+    - uses: pre-commit/action@v2.0.0

{fusesoc-2.3 → fusesoc-2.4.2}/NEWS

@@ -1,3 +1,45 @@
+2.4.2 2024-01-07 Olof Kindgren <olof.kindgren@gmail.com>
+======================================================
+
+* Support lists in file_input_parameters
+* Add SVN provider
+* Support file-specific defines
+* Always build non-cached generators in work_root
+* Add splitlib filter
+* Warn about non-deterministic virtual cores
+
+Contributors:
+Erik Bånvik <erik.public@gmail.com>
+James Wainwright <james.wainwright@lowrisc.org>
+Mario Werner <nioshd@gmail.com>
+Nazar Kazakov <nazar.kazakov@codethink.co.uk>
+Nico Rumpeltin <nico@rumpeltin.de>
+Olof Kindgren <olof.kindgren@gmail.com>
+
+2.4.1 2024-10-07 Olof Kindgren <olof.kindgren@gmail.com>
+======================================================
+
+* Fix broken documentation builds
+
+Contributors:
+Olof Kindgren <olof.kindgren@gmail.com>
+
+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

{fusesoc-2.3 → fusesoc-2.4.2}/PKG-INFO

@@ -1,25 +1,33 @@
 Metadata-Version: 2.1
 Name: fusesoc
-Version: 2.3
-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.2
+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.9.1
+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
 
@@ -53,7 +61,7 @@ full list of system requirements and installation instructions in the
 ### Quick start
 
 To check if FuseSoC is working, and to get an initial feeling for how FuseSoC
-works, you can try to simulate a simple hardware design from our core libray.
+works, you can try to simulate a simple hardware design from our core library.
 
 First, create and enter an empty workspace
 
@@ -79,7 +87,7 @@ add e.g. `--tool=modelsim` or `--tool=xcelium` between `run` and `i2c`.
 Did it work? Great! FuseSoC can be used to create FPGA images, perform
 linting, manage your IP libraries or do formal verification as well.
 Check out the [online documentation](https://fusesoc.readthedocs.io/en/stable/)
-documentation to learn more about creating your own core files and using
+to learn more about creating your own core files and using
 existing ones. If it didn't work, please get in touch (see below).
 
 ## Next steps

{fusesoc-2.3 → fusesoc-2.4.2}/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
 
@@ -36,7 +35,7 @@ full list of system requirements and installation instructions in the
 ### Quick start
 
 To check if FuseSoC is working, and to get an initial feeling for how FuseSoC
-works, you can try to simulate a simple hardware design from our core libray.
+works, you can try to simulate a simple hardware design from our core library.
 
 First, create and enter an empty workspace
 
@@ -62,7 +61,7 @@ add e.g. `--tool=modelsim` or `--tool=xcelium` between `run` and `i2c`.
 Did it work? Great! FuseSoC can be used to create FPGA images, perform
 linting, manage your IP libraries or do formal verification as well.
 Check out the [online documentation](https://fusesoc.readthedocs.io/en/stable/)
-documentation to learn more about creating your own core files and using
+to learn more about creating your own core files and using
 existing ones. If it didn't work, please get in touch (see below).
 
 ## Next steps

{fusesoc-2.3 → fusesoc-2.4.2}/doc/source/conf.py

@@ -12,7 +12,6 @@
 import os
 import sys
 from datetime import datetime
-from distutils.version import LooseVersion
 
 import jsonschema2md
 
@@ -35,11 +34,13 @@ project = "FuseSoC"
 copyright = f"2018-{datetime.now().year}, Olof Kindgren"
 author = "Olof Kindgren"
 
+from importlib.metadata import version as get_version
+
 # The full version, including alpha/beta/rc tags.
-release = fusesoc.__version__
+release: str = get_version("fusesoc")
+
 # The short X.Y version.
-v_major, v_minor = LooseVersion(release).version[:2]
-version = f"{v_major}.{v_minor}"
+version: str = ".".join(release.split(".")[:2])
 
 # -- General configuration ---------------------------------------------------
 
@@ -62,7 +63,7 @@ extensions = [
     "myst_parser",
 ]
 
-intersphinx_mapping = {"https://docs.python.org/3": None}
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
 
 
 # Add any paths that contain templates here, relative to this directory.

{fusesoc-2.3 → fusesoc-2.4.2}/doc/source/index.rst

@@ -8,7 +8,7 @@ This documentation contains material for different audiences.
 
 The :doc:`User Guide <user/index>` explains how to get started with FuseSoC, starting from the installation.
 
-The :doc:`Reference Guide <ref/index>` provides a detailled description of all file formats and APIs.
+The :doc:`Reference Guide <ref/index>` provides a detailed description of all file formats and APIs.
 
 The :doc:`Developer's Guide <dev/index>` is aimed at developers of FuseSoC itself.
 It explains how to set up a development environment, how the source code is structured, and how patches and bug reports can be submitted to the project.

{fusesoc-2.3 → fusesoc-2.4.2}/doc/source/ref/capi1.rst

@@ -361,7 +361,7 @@ main
      - Supported simulators. Valid values are
        icarus, modelsim, verilator, isim and
        xsim. Each simulator have a dedicated
-       section desribed elsewhere in this
+       section described elsewhere in this
        document
 
 

{fusesoc-2.3 → fusesoc-2.4.2}/doc/source/ref/migrations.rst

@@ -278,7 +278,7 @@ Why
 ---
 As an aid for scripts executed during the build process, a number of environment variables were defined. Unfortunately this was done without too much thought and as time moved on, some of these turned out to be a maintenance burden without bringing much benefit, and in some cases without ever being used.
 
-At the same time, the introduction of VLNV and dependency ranges has introduced non-determinism in where the output of a build ends up. For these reasons, it was determined to redefine the rarely used `build_root` variable to point to the the directory containing the work root and exported files. A `--build-root` command-line switch is introduced to explictly set a build_root. Setting `build_root` in `fusesoc.conf` will keep working the same way as before, but the command-line switch takes precedence. CAPI1 cores will no longer export the `BUILD_ROOT` environment variable.
+At the same time, the introduction of VLNV and dependency ranges has introduced non-determinism in where the output of a build ends up. For these reasons, it was determined to redefine the rarely used `build_root` variable to point to the the directory containing the work root and exported files. A `--build-root` command-line switch is introduced to explicitly set a build_root. Setting `build_root` in `fusesoc.conf` will keep working the same way as before, but the command-line switch takes precedence. CAPI1 cores will no longer export the `BUILD_ROOT` environment variable.
 
 These changes affects the following cases:
 

{fusesoc-2.3 → fusesoc-2.4.2}/doc/source/user/build_system/core_files.rst

@@ -165,12 +165,12 @@ For each named file set, several keys are supported:
 Source files
 ~~~~~~~~~~~~
 
-Source files are resolved relative to the location of the core file and must be stored in the same directory as the core file, or in a subdirectory of it.
+For local cores, source files are resolved relative to the location of the core file and must be stored in the same directory as the core file, or in a subdirectory of it. For remote cores, file names are typically relative to the repository or archive root.
 Source file names cannot be absolute paths, or start with ``../``.
 
-Optionally, source files can have attributes; the file ``macros.vh`` is an example of that.
+Optionally, source files can have attributes; the file ``macros.svh`` is an example of that.
 When specifying attributes, end the file name with a colon (``:``), and specify attributes as key-value pairs below it.
-(Alternatively, the equivalent short form syntax can be used, e.g. ``macros.vh: {is_include_file: true}``.)
+(Alternatively, the equivalent short form syntax can be used, e.g. ``macros.svh: {is_include_file: true}``.)
 
 The most common attributes are:
 

{fusesoc-2.3 → fusesoc-2.4.2}/doc/source/user/build_system/dependencies.rst

@@ -12,7 +12,7 @@ This section explains how dependencies are specified, how they are resolved by F
 A dependency example: DualBlinky
 --------------------------------
 
-We introduced the basic FuseSoC features by creating an reusable core called Blinky.
+We introduced the basic FuseSoC features by creating a reusable core called Blinky.
 To illustrate the concept of dependencies in FuseSoC we employ another example: DualBlinky, the "dual-core" version of Blinky.
 Again, all source code is available in the `FuseSoC source tree <https://github.com/olofk/fusesoc>`_ in the ``tests/userguide/dualblinky`` directory.
 
@@ -71,14 +71,14 @@ The following rules apply.
 
 * Files from dependencies are inserted into the file list before the files in the file set where the dependency is declared.
 * The order in which dependencies are listed in the ``depend`` section does not imply any ordering.
-  That is, specifiying ``depend: [A, B]`` does not guarantee that files from core ``A`` are included before the ones from core ``B``.
+  That is, specifying ``depend: [A, B]`` does not guarantee that files from core ``A`` are included before the ones from core ``B``.
   (If such an order is desired, make core ``B`` depend on ``A``.)
 
 What happens if a dependency is specified?
 ------------------------------------------
 
 Declaring a dependency includes the dependent core in the build.
-More specificially, the following sections specified in the ``default`` target of the dependent core are included:
+More specifically, the following sections specified in the ``default`` target of the dependent core are included:
 
 * ``filesets``: File sets to include.
 * ``hooks``: A list of hooks to execute.
@@ -94,7 +94,7 @@ Version constraints
 
 Version constraints specify which version of a dependent core can be used, and which versions are incompatible.
 
-Within a :term:`core file`, version constraints are expressed by prefixing a core name with a version comparision operator.
+Within a :term:`core file`, version constraints are expressed by prefixing a core name with a version comparison operator.
 The following version comparison operators are available.
 
 .. list-table:: Version comparison operators

fusesoc-2.4.2/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.3 → fusesoc-2.4.2}/doc/source/user/build_system/flow_options.rst

@@ -11,7 +11,7 @@ At the same time, a certain level of tool-specific configurability is required t
 
 There are two categories of options available for the Edalize flows. *Flow options* that affect how the tools are chained together (the flow graph) and *tool options* for the individual tools to be run as part of the flow. This means that since the flow options influence which tools that will be run, some tool options only become available for certain combinations of flow options.
 
-Only one flow can be defined for a target, but the flow it self can be configured in different ways. The example below shows how the `test` target selects and configures a flow. The `flow` key selectes the flow itself. The selected `sim` flow has a *flow option* called `tool` that decides which simulator to use. `iverilog_options` and `vlog_options` are tool options for Icarus Verilog and Siemens QuestaSim/ModelSim and will be passed to the approriate tool if it is present in the flow graph.
+Only one flow can be defined for a target, but the flow itself can be configured in different ways. The example below shows how the `test` target selects and configures a flow. The `flow` key selects the flow itself. The selected `sim` flow has a *flow option* called `tool` that decides which simulator to use. `iverilog_options` and `vlog_options` are tool options for Icarus Verilog and Siemens QuestaSim/ModelSim and will be passed to the appropriate tool if it is present in the flow graph.
 
 This setup selects icarus as the tool, which means the `vlog_options` will not be used. However, all *flow options* and *tool options* are also automatically available on the command-line, which means that passing `--tool=modelsim` as a backend parameter will override the tool setting from the target. The same can be done for the two tool options, with the difference that for flow or tool option that are lists, any additional values passed on the command-line will append rather than replace the values in the core description file.
 

{fusesoc-2.3 → fusesoc-2.4.2}/doc/source/user/build_system/generators.rst

@@ -135,7 +135,7 @@ The final piece of the generators machinery is to run a generator with some spec
               offset: 0xf0000000
               size: 1024
 
-The above core file snippet will register a parametrized generator instance with the name wb_intercon. It will use the generator called `wb_intercon_gen` which FuseSoC has previously found in the depedency tree. Everything listed under the `parameters` key is instance-specific configuration to be sent to the generator.
+The above core file snippet will register a parametrized generator instance with the name wb_intercon. It will use the generator called `wb_intercon_gen` which FuseSoC has previously found in the dependency tree. Everything listed under the `parameters` key is instance-specific configuration to be sent to the generator.
 
 Just registering a generate section will not cause the generator to be invoked. It must also be listed in the target and the generator to be used must be in the dependency tree. The following snippet adds the parameterized generator to the `default` target and adds an explicit dependency on the core that contains the generator. As CAPI2 cores only allow filesets to have dependencies, an empty fileset for this purpose must be created
 
@@ -169,7 +169,7 @@ Generator Cache
 ---------------
 Instead of fusesoc rerunning a generator each time and producing the same result it is possible to configure fusesoc to cache generator output and try to detect if a new run would produce the same output. Since there is no generic way of doing this that will fit all generators a couple of different methods for caching and detecting changes are available.
 
-The `generators` option `cache_type` is used for configuring type of caching. If set to `none` (or if option is omitted) no caching will be used. If set to `input` fusesoc will calculate a SHA256 hash of the generator input yaml file data and use this hash for detecting if something has changed and a rerun would be needed. This would happen if some data in the core file `generate` section, for instance `paramaters`, has changed.
+The `generators` option `cache_type` is used for configuring type of caching. If set to `none` (or if option is omitted) no caching will be used. If set to `input` fusesoc will calculate a SHA256 hash of the generator input yaml file data and use this hash for detecting if something has changed and a rerun would be needed. This would happen if some data in the core file `generate` section, for instance `parameters`, has changed.
 
 If `cache_type` is set to `generator` fusesoc will pass the responsibility for detecting if the previous run to the generator is still up to date. In this mode the generator will always be called and the output directory will be saved.
 

{fusesoc-2.3 → fusesoc-2.4.2}/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.3 → fusesoc-2.4.2}/doc/source/user/build_system/tool_options.rst

@@ -26,7 +26,7 @@ Typically, these keys are called ``BINARYNAME_options``, and they take a list of
 The example below shows how tool options for Icarus Verilog (``icarus``) and Mentor ModelSim (``modelsim``) are set.
 
 * The ``iverilog`` binary will be called with the ``-g2012`` command-line argument, indicating that SystemVerilog 2012 support should be enabled.
-* Similarily, for ModelSim the argument ``-timescale=1ns/1ns`` will be passed to the ``vlog`` binary, which elaborates the design.
+* Similarly, for ModelSim the argument ``-timescale=1ns/1ns`` will be passed to the ``vlog`` binary, which elaborates the design.
 
 .. code-block:: yaml
 

fusesoc-2.4.2/doc/source/user/cli.rst

@@ -0,0 +1,56 @@
+.. _ug_cli:
+
+***************
+Running FuseSoC
+***************
+
+FuseSoC is a command-line tool; this section explains how to use it.
+The following content is aimed at users who already have a hardware design which uses FuseSoC.
+
+Build a design
+==============
+
+The ``fusesoc run`` group of commands is used to setup, build, and (if possible) run a design.
+The exact actions taken by the individual steps depend on the toolflow.
+
+::
+
+    usage: fusesoc run [-h] [--no-export] [--build-root BUILD_ROOT] [--setup] [--build] [--run] [--target TARGET] [--tool TOOL] [--flag FLAG] [--system-name SYSTEM_NAME] system ...
+
+    positional arguments:
+      system                Select a system to operate on
+      backendargs           arguments to be sent to backend
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      --no-export           Reference source files from their current location instead of exporting to a build tree
+      --build-root BUILD_ROOT
+                            Output directory for build. Defaults to build/$VLNV
+      --setup               Execute setup stage
+      --build               Execute build stage
+      --run                 Execute run stage
+      --target TARGET       Override default target
+      --tool TOOL           Override default tool for target
+      --flag FLAG           Set custom use flags. Can be specified multiple times
+      --system-name SYSTEM_NAME
+                            Override default VLNV name for system
+
+When FuseSoC is invoked with the run command, it will create an empty working directory called `work_root` internally, where it by default will create all project files, copy all used source files, build and optionally run the project.
+
+Setup, build and run
+--------------------
+
+The process of running EDA tools is divided into three steps called *setup*, *build* and *run*. The *setup* stage creates the working directory and all project files. The *build* stage runs one or more EDA tools to build an artifact, e.g. a GDS, simulation model or FPGA image. The *run* stage is only implemented for some tool flows, such as simulation flows where it runs the simulation. Some FPGA flows uses the *run* stage to program an FPGA device.
+
+Normally FuseSoC runs all three stages, but if the `--setup` flag is added, it will stop after the setup stage and if the `--build` flag is set it will stop after the build stage. Many of the newer backends don't need these flags and will instead only run setup or build when input files or options have changed.
+
+Work root
+---------
+`work_root` is a private working directory and should not be shared between different builds. It is however perfectly fine to reuse the working directory for e.g. running several simulations using different runtime options as long as the build-time options and source files are not modified.
+
+By default, FuseSoC will use `build/<sanitized VLNV>/<target>`, where `<sanitized VLNV>` is the top-level VLNV with underscore instead of colon as the separator. For the Flow API, `<target>` is just the name of the target in the core description file, e.g. `sim`. For the old Tool API, it is a combination of target name and the tool backend, e.g. `sim-verilator`. The work root directory can be changed with the `--work-root` option.
+
+Exporting source files
+----------------------
+
+The standard behavior for FuseSoC is to copy all used source files into a subdirectory of the work root. This has three advantages. The work root is self-contained with all the source files and can be copied elsewhere for archival purposes or to build on another machine. No stray files are picked up by mistake from the original source directories. It is always possible to know from exactly which files a build was created. Despite this, there are situations where it is preferable to reference the source files from their original location. This can be done by adding the `--no-export` flag.

{fusesoc-2.3 → fusesoc-2.4.2}/doc/source/user/introduction.rst

@@ -20,7 +20,7 @@ Its main purpose is to increase reuse of IP (Intellectual Property) cores and be
 
 - set up continuous integration
 
-**FuseSoC is non-intrusive** Most existing designs doesn't need any changes to work with FuseSoC. Any FuseSoC-specific patches can be applied on the fly during implementation or simulation
+**FuseSoC is non-intrusive** Most existing designs don't need any changes to work with FuseSoC. Any FuseSoC-specific patches can be applied on the fly during implementation or simulation
 
 **FuseSoC is modular** It can be used as an end-to-end flow, to create initial project files for an EDA tool or integrate with your custom workflow
 

fusesoc-2.4.2/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.3 → fusesoc-2.4.2}/doc/source/user/package_manager/index.rst

@@ -54,7 +54,7 @@ FuseSoC is launched. The library locations specified from the
 command-line will be parsed after those in ``fusesoc.conf``
 
 For each library location, FuseSoC will recursively search for files
-with a *.core* suffix. Each of these files will be parsed and addded to
+with a *.core* suffix. Each of these files will be parsed and added to
 the in-memory FuseSoC database if they are valid ``.core`` files.
 
 Several ``.core`` files can reside in the same directory and they will all be parsed.