wu-arch/chipyard
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Merge branch 'main' of https://github.com/ucb-bar/chipyard into openroad

Browse Source
This commit is contained in:
Nayiri K
2022-09-27 12:07:07 -07:00
parent 79772d8a64 018aa7e1f0
commit e61638c9e8
76 changed files with 11450 additions and 1039 deletions
Download Patch File Download Diff File Expand all files Collapse all files

125
docs/Chipyard-Basics/Initial-Repo-Setup.rst
View File

@@ -1,33 +1,58 @@
Initial Repository Setup
========================================================
Requirements
Prerequisites
-------------------------------------------
Chipyard is developed and tested on Linux-based systems.
.. Warning:: It is possible to use this on macOS or other BSD-based systems, although GNU tools will need to be installed; it is also recommended to install the RISC-V toolchain from ``brew``.
.. Warning:: It is possible to use this on macOS or other BSD-based systems, although GNU tools will need to be installed;
it is also recommended to install the RISC-V toolchain from ``brew``.
.. Warning:: Working under Windows is not recommended.
Running on AWS EC2 with FireSim
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In CentOS-based platforms, we recommend installing the following dependencies:
If you plan on using Chipyard alongside FireSim on AWS EC2 instances, you should refer to the :fsim_doc:`FireSim documentation <>`.
Specifically, you should follow the :fsim_doc:`Initial Setup/Installation <Initial-Setup/index.html>`
section of the docs up until :fsim_doc:`Setting up the FireSim Repo <Initial-Setup/Setting-up-your-Manager-Instance.html#setting-up-the-firesim-repo>`.
At that point, instead of cloning FireSim you can clone Chipyard by following :ref:`Chipyard-Basics/Initial-Repo-Setup:Setting up the Chipyard Repo`.
.. include:: /../scripts/centos-req.sh
:code: bash
Default Requirements Installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In Ubuntu/Debian-based platforms (Ubuntu), we recommend installing the following dependencies.
These dependencies were written based on Ubuntu 16.04 LTS and 18.04 LTS - If they don't work for you, you can try out the Docker image (:ref:`Chipyard-Basics/Initial-Repo-Setup:Pre-built Docker Image`) before manually installing or removing dependencies:
In Chipyard, we use the `Conda <https://docs.conda.io/en/latest/>`__ package manager to help manage system dependencies.
Conda allows users to create an "environment" that holds system dependencies like ``make``, ``gcc``, etc.
.. include:: /../scripts/ubuntu-req.sh
:code: bash
.. Note:: Chipyard can also run on systems without a Conda installation. However, users on these systems must manually install toolchains and dependencies.
.. Note:: When running on an Amazon Web Services EC2 FPGA-development instance (for FireSim), FireSim includes a machine setup script that will install all of the aforementioned dependencies (and some additional ones).
First, Chipyard requires Conda to be installed on the system.
Please refer to the `Conda installation instructions <https://github.com/conda-forge/miniforge/#download>`__ on how to install Conda with the **Miniforge** installer.
Afterwards, verify that Conda is a sufficient version (we test on version 4.12.0 but higher is most likely fine).
.. Note:: If you have installed conda separately from this documentation (i.e. from miniconda or full Anaconda), please ensure you follow https://conda-forge.org/docs/user/introduction.html#how-can-i-install-packages-from-conda-forge to use ``conda-forge`` packages without any issues.
.. code-block:: shell
conda --version # must be version 4.12.0 or higher
After Conda is installed and is on your ``PATH``, we need to install a version of ``git`` to initially checkout the repository.
For this you can use the system package manager like ``yum`` or ``apt`` to install ``git``.
This ``git`` is only used to first checkout the repository, we will later install a newer version of ``git`` with Conda.
Finally we need to install ``conda-lock`` into the ``base`` conda environment.
This is done by the following:
.. code-block:: shell
conda install -n base conda-lock
conda activate base
Setting up the Chipyard Repo
-------------------------------------------
Start by fetching Chipyard's sources. Run:
Start by checking out the proper Chipyard version. Run:
.. parsed-literal::
@@ -36,40 +61,60 @@ Start by fetching Chipyard's sources. Run:
# checkout latest official chipyard release
# note: this may not be the latest release if the documentation version != "stable"
git checkout |version|
./scripts/init-submodules-no-riscv-tools.sh
This will initialize and checkout all of the necessary git submodules.
This will also validate that you are on a tagged branch, otherwise it will prompt for confirmation.
When updating Chipyard to a new version, you will also want to rerun this script to update the submodules.
Using git directly will try to initialize all submodules; this is not recommended unless you expressly desire this behavior.
.. _build-toolchains:
Building a Toolchain
------------------------
The `toolchains` directory contains toolchains that include a cross-compiler toolchain, frontend server, and proxy kernel, which you will need in order to compile code to RISC-V instructions and run them on your design.
Currently there are two toolchains, one for normal RISC-V programs, and another for Hwacha (``esp-tools``).
For custom installations, Each tool within the toolchains contains individual installation procedures within its README file.
To get a basic installation (which is the only thing needed for most Chipyard use-cases), just the following steps are necessary.
This will take about 20-30 minutes. You can expedite the process by setting a ``make`` environment variable to use parallel cores: ``export MAKEFLAGS=-j8``.
Next run the following script to create Chipyard's Conda environment including a pre-built RISC-V toolchain.
There are two toolchains, one for normal RISC-V programs called ``riscv-tools`` which is the one needed for most Chipyard use-cases, and another for Hwacha/Gemmini called ``esp-tools``.
Run the following script based off which compiler you would like to use.
.. code-block:: shell
./scripts/build-toolchains.sh riscv-tools # for a normal risc-v toolchain
./build-setup.sh riscv-tools # or esp-tools
.. Note:: If you are planning to use the Hwacha vector unit, or other RoCC-based accelerators, you should build the esp-tools toolchain by adding the ``esp-tools`` argument to the script above.
If you are running on an Amazon Web Services EC2 instance, intending to use FireSim, you can also use the ``--ec2fast`` flag for an expedited installation of a pre-compiled toolchain.
This script wraps around the conda environment initialization process and also runs the ``init-submodules-no-riscv-tools.sh`` and ``build-toolchain-extra.sh`` scripts.
Once the script is run, a ``env.sh`` file is emitted that sets the ``PATH``, ``RISCV``, and ``LD_LIBRARY_PATH`` environment variables.
You can put this in your ``.bashrc`` or equivalent environment setup file to get the proper variables, or directly include it in your current environment:
The ``init-subodules-no-riscv-tools.sh`` script will initialize and checkout all of the necessary git submodules.
This will also validate that you are on a tagged branch, otherwise it will prompt for confirmation.
When updating Chipyard to a new version, you will also want to rerun this script to update the submodules.
Using ``git`` directly will try to initialize all submodules; this is not recommended unless you expressly desire this behavior.
The ``build-toolchain-extra.sh`` script will install extra toolchain utilities/tests used by Chipyard.
This command builds utilities like Spike, RISC-V Proxy Kernel, libgloss, and RISC-V tests from source for a specific toolchain type.
.. Note:: By default, the ``build-toolchain-extra.sh`` script installs to ``$CONDA_PREFIX/<toolchain-type>``. Thus, if you uninstall the compiler using ``conda remove`` these utilities/tests will also have to be re-installed/built.
.. Note:: If you already have a working conda environment setup, separate Chipyard clones can use that pre-used environment in combination with running the aforementioned scripts yourself (``init-submodules...`` and ``build-toolchain...``).
.. Note:: If you are a power user and would like to build your own compiler/toolchain, you can refer to the https://github.com/ucb-bar/riscv-tools-feedstock and https://github.com/ucb-bar/esp-tools-feedstock repositories (submoduled in the ``toolchains/*`` directories) on how to build the compiler yourself.
By running the following command you should see a environment listed with the path ``$CHIPYARD_DIRECTORY/.conda-env``.
.. code-block:: shell
conda env list
.. Note:: Refer to FireSim's :fsim_doc:`Conda documentation <Advanced-Usage/Conda.html>` on more information
on how to use Conda and some of its benefits.
Sourcing ``env.sh``
-------------------
Once setup is complete, an emitted ``env.sh`` file should exist in the top-level repository.
This file activates the conda environment created in ``build-setup.sh`` and sets up necessary environment variables needed for future Chipyard steps (needed for the ``make`` system to work properly).
Once the script is run, the ``PATH``, ``RISCV``, and ``LD_LIBRARY_PATH`` environment variables will be set properly for the toolchain requested.
You can source this file in your ``.bashrc`` or equivalent environment setup file to get the proper variables, or directly include it in your current environment:
.. code-block:: shell
source ./env.sh
These variables need to be set for the ``make`` system to work properly.
.. Warning:: This ``env.sh`` file should always be sourced before running any ``make`` commands.
.. Note:: You can deactivate/activate a compiler/toolchain (but keep it installed) by running ``source $CONDA_PREFIX/etc/conda/deactivate.d/deactivate-${PKG_NAME}.sh`` or ``$CONDA_PREFIX/etc/conda/activate.d/activate-${PKG_NAME}.sh`` (``PKG_NAME`` for example is ``ucb-bar-riscv-tools``). This will modify the aforementioned 3 environment variables.
.. Warning:: ``env.sh`` files are generated per-Chipyard repository.
In a multi-Chipyard repository setup, it is possible to source multiple ``env.sh`` files (in any order).
However, it is recommended that the final ``env.sh`` file sourced is the ``env.sh`` located in the
Chipyard repo that you expect to run ``make`` commands in.
Pre-built Docker Image
-------------------------------------------
@@ -115,20 +160,22 @@ In order to upgrade between Chipyard versions, we recommend using a fresh clone
Chipyard is a complex framework that depends on a mix of build systems and scripts. Specifically, it relies on git submodules, on sbt build files, and on custom written bash scripts and generated files.
For this reason, upgrading between Chipyard versions is **not** as trivial as just running ``git submodule update -recursive``. This will result in recursive cloning of large submodules that are not necessarily used within your specific Chipyard environments. Furthermore, it will not resolve the status of stale state generated files which may not be compatible between release versions.
For this reason, upgrading between Chipyard versions is **not** as trivial as just running ``git submodule update --recursive``. This will result in recursive cloning of large submodules that are not necessarily used within your specific Chipyard environments.
Furthermore, it will not resolve the status of stale state generated files which may not be compatible between release versions.
If you are an advanced git user, an alternative approach to a fresh repository clone may be to run ``git clean -dfx``, and then run the standard Chipyard setup sequence. This approach is dangerous, and **not-recommended** for users who are not deeply familiar with git, since it "blows up" the repository state and removes all untracked and modified files without warning. Hence, if you were working on custom un-committed changes, you would lose them.
If you are an advanced git user, an alternative approach to a fresh repository clone may be to run ``git clean -dfx``, and then run the standard Chipyard setup sequence.
This approach is dangerous, and **not-recommended** for users who are not deeply familiar with git, since it "blows up" the repository state and removes all untracked and modified files without warning.
Hence, if you were working on custom un-committed changes, you would lose them.
If you would still like to try to perform an in-place manual version upgrade (**not-recommended**), we recommend at least trying to resolve stale state in the following areas:
* Delete stale ``target`` directories generated by sbt.
* Delete jar collateral generated by FIRRTL (``lib/firrtl.jar``)
* Re-generate generated scripts and source files (for example, ``env.sh``)
* Re-generating/deleting target software state (Linux kernel binaries, Linux images) within FireMarshal
This is by no means a comprehensive list of potential stale state within Chipyard. Hence, as mentioned earlier, the recommended method for a Chipyard version upgrade is a fresh clone (or a merge, and then a fresh clone).
This is by no means a comprehensive list of potential stale state within Chipyard.
Hence, as mentioned earlier, the recommended method for a Chipyard version upgrade is a fresh clone (or a merge, and then a fresh clone).

2
docs/Customization/Boot-Process.rst
View File

@@ -74,6 +74,6 @@ mode, thus starting userspace execution.
The easiest way to build a BBL image that boots Linux is to use the FireMarshal
tool that lives in the `firesim-software <https://github.com/firesim/firesim-software>`_
repository. Directions on how to use FireMarshal can be found in the
`FireSim documentation <https://docs.fires.im/en/latest/Advanced-Usage/FireMarshal/index.html>`_.
:fsim_doc:`FireSim documentation <Advanced-Usage/FireMarshal/index.html>`.
Using FireMarshal, you can add custom kernel configurations and userspace software
to your workload.

26
docs/Simulation/FPGA-Accelerated-Simulation.rst
View File

@@ -6,30 +6,28 @@ FPGA-Accelerated Simulation
FireSim
-----------------------
`FireSim <https://fires.im/>`__ is an open-source cycle-accurate FPGA-accelerated full-system hardware simulation platform that runs on cloud FPGAs (Amazon EC2 F1).
`FireSim <https://fires.im/>`__ is an open-source cycle-accurate FPGA-accelerated full-system hardware simulation platform that runs on FPGAs (Amazon EC2 F1 FPGAs and local FPGAs).
FireSim allows RTL-level simulation at orders-of-magnitude faster speeds than software RTL simulators.
FireSim also provides additional device models to allow full-system simulation, including memory models and network models.
FireSim currently supports running only on Amazon EC2 F1 FPGA-enabled virtual instances.
In order to simulate your Chipyard design using FireSim, if you have not
already, follow the initial EC2 setup instructions as detailed in the `FireSim
documentation <http://docs.fires.im/en/latest/Initial-Setup/index.html>`__.
Then clone Chipyard onto your FireSim manager
instance, and setup your Chipyard repository as you would normally.
FireSim supports running on Amazon EC2 F1 FPGA-enabled cloud instances and on locally managed Linux machines with FPGAs attached.
The rest of this documentation assumes you are running on an Amazon EC2 F1 FPGA-enabled virtual instance.
In order to simuate your Chipyard design using FireSim, make sure to follow the repository setup as described by
:ref:`Chipyard-Basics/Initial-Repo-Setup:Initial Repository Setup`, if you have not already.
Next, initalize FireSim as a library in Chipyard by running:
.. code-block:: shell
# At the root of your chipyard repo
./scripts/firesim-setup.sh --fast
./scripts/firesim-setup.sh
``firesim-setup.sh`` initializes additional submodules and then invokes
firesim's ``build-setup.sh`` script adding ``--library`` to properly
initialize FireSim as a library submodule in chipyard. You may run
FireSim's ``build-setup.sh`` script adding ``--library`` to properly
initialize FireSim as a library submodule in Chipyard. You may run
``./sims/firesim/build-setup.sh --help`` to see more options.
Finally, source the following environment at the root of the firesim directory:
Finally, source the following environment at the root of the FireSim directory:
.. code-block:: shell
@@ -40,13 +38,13 @@ Finally, source the following environment at the root of the firesim directory:
.. Note:: Every time you want to use FireSim with a fresh shell, you must source this ``sourceme-f1-manager.sh``
At this point you're ready to use FireSim with Chipyard. If you're not already
familiar with FireSim, please return to the `FireSim Docs
<https://docs.fires.im/en/latest/Initial-Setup/Setting-up-your-Manager-Instance.html#completing-setup-using-the-manager>`__,
familiar with FireSim, please return to the :fsim_doc:`FireSim Docs <Initial-Setup/Setting-up-your-Manager-Instance.html#completing-setup-using-the-manager>`,
and proceed with the rest of the tutorial.
Running your Design in FireSim
------------------------------
Converting a Chipyard config (one in ``chipyard/src/main/scala`` to run in FireSim is simple, and can be done either through the traditional configuration system or through FireSim's build-recipes scheme.
Converting a Chipyard config (one in ``chipyard/src/main/scala`` to run in FireSim is simple, and can be done either through the traditional configuration system or through FireSim's build-recipes scheme.
A FireSim simulation requires 3 additional config fragments:

16
docs/conf.py
View File

@@ -32,14 +32,17 @@ import subprocess
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc',
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.mathjax',
'sphinx.ext.ifconfig',
'sphinx.ext.viewcode',
'sphinx.ext.githubpages',
'sphinx.ext.autosectionlabel']
'sphinx.ext.autosectionlabel',
'sphinx.ext.extlinks',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -67,6 +70,8 @@ if on_rtd:
for item, value in os.environ.items():
print("[READTHEDOCS] {} = {}".format(item, value))
# default to latest for non rtd builds (this will be overridden on rtd)
rtd_version = "latest"
if on_rtd:
rtd_version = os.environ.get("READTHEDOCS_VERSION")
if rtd_version == "latest":
@@ -93,7 +98,7 @@ release = version
#
# 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.
@@ -227,3 +232,8 @@ intersphinx_mapping = {'python' : ('https://docs.python.org/', None),
# resolve label conflict between documents
autosectionlabel_prefix_document = True
# shorten FireSim references
extlinks = {
'fsim_doc' : ('https://docs.fires.im/en/' + rtd_version + '/%s', 'fsim_doc %s')
}

5
docs/requirements.txt
View File

@@ -1,5 +0,0 @@
Sphinx==1.8.5
Pygments==2.7.4
sphinx-autobuild
sphinx_rtd_theme==0.2.5b1
docutils==0.16