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

Doc update

Browse Source
This commit is contained in:
Abraham Gonzalez
2022-09-12 18:38:44 +00:00
parent 50fd8d99f1
commit 27acda4d1b
3 changed files with 21 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
build-setup.sh
View File

@@ -74,7 +74,7 @@ fi
# use conda-lock to create env # use conda-lock to create env
conda-lock install -p $DIR/.conda-env $LOCKFILE conda-lock install -p $DIR/.conda-env $LOCKFILE
eval "$(conda shell.bash hook)" source $DIR/.conda-env/etc/profile.d/conda.sh
conda activate $DIR/.conda-env conda activate $DIR/.conda-env
$DIR/scripts/init-submodules-no-riscv-tools.sh $SKIP_VALIDATE_FLAG $DIR/scripts/init-submodules-no-riscv-tools.sh $SKIP_VALIDATE_FLAG

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

@@ -1,7 +1,7 @@
Initial Repository Setup Initial Repository Setup
======================================================== ========================================================
Requirements Prerequisites
------------------------------------------- -------------------------------------------
Chipyard is developed and tested on Linux-based systems. Chipyard is developed and tested on Linux-based systems.
@@ -14,7 +14,7 @@ Chipyard is developed and tested on Linux-based systems.
Running on AWS EC2 with FireSim Running on AWS EC2 with FireSim
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you plan on using Chipyard alongside FireSim, you should refer to the :fsim_doc:`FireSim documentation <>`. 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/Simulation <Initial-Setup/index.html>` Specifically, you should follow the :fsim_doc:`Initial Setup/Simulation <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>`. 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 checking out FireSim you can checkout Chipyard by following :ref:`Chipyard-Basics/Initial-Repo-Setup:Setting up the Chipyard Repo`. At that point, instead of checking out FireSim you can checkout Chipyard by following :ref:`Chipyard-Basics/Initial-Repo-Setup:Setting up the Chipyard Repo`.
@@ -28,8 +28,8 @@ Conda allows users to create an "environment" that holds system dependencies lik
.. Note:: Chipyard can also run on systems without a Conda installation. However, users on these systems must manually install toolchains and dependencies. .. Note:: Chipyard can also run on systems without a Conda installation. However, users on these systems must manually install toolchains and dependencies.
First Chipyard requires there to be Conda installed on the system. First Chipyard requires there to be Conda 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. 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/4.13.0 but higher is most likely fine). 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. .. 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.
@@ -62,18 +62,13 @@ Start by checking out the proper Chipyard's version. Run:
# note: this may not be the latest release if the documentation version != "stable" # note: this may not be the latest release if the documentation version != "stable"
git checkout |version| git checkout |version|
.. Warning:: When running on an Amazon Web Services EC2 FPGA-development instance
(for FireSim), FireSim includes a similar machine setup script that will install all
of the aforementioned dependencies (and some additional ones) and will activate the
proper conda environment. **Skip the rest of this section.**
Next run the following script to create Chipyard's Conda environment including a pre-built RISC-V toolchain. 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``. 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. Run the following script based off which compiler you would like to use.
.. code-block:: shell .. code-block:: shell
./setup.sh --env-name chipyard riscv-tools # or esp-tools ./build-setup.sh riscv-tools # or esp-tools
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. 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.
@@ -91,7 +86,7 @@ This command builds utilities like Spike, RISC-V Proxy Kernel, libgloss, and RIS
.. 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. .. 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 "chipyard" environment listed. By running the following command you should see a environment listed with the path ``$CHIPYARD_DIRECTORY/.conda-env``.
.. code-block:: shell .. code-block:: shell
@@ -100,21 +95,12 @@ By running the following command you should see a "chipyard" environment listed.
.. Note:: Refer to FireSim's :fsim_doc:`Conda documentation <Advanced-Usage/Conda.html>` on more information .. 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. on how to use Conda and some of its benefits.
Next go ahead and activate the conda environment that was setup.
.. code-block:: shell
conda activate chipyard
Once the command is run, the ``PATH``, ``RISCV``, and ``LD_LIBRARY_PATH`` environment variables will be set properly.
.. 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.
Sourcing ``env.sh`` Sourcing ``env.sh``
------------------- -------------------
Once setup is complete, an emitted ``env.sh`` file should exist in the top-level repository. Once setup is complete, an emitted ``env.sh`` file should exist in the top-level repository.
This sets up necessary environment variables needed for future Chipyard steps (needed for the ``make`` system to work properly). 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: 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 .. code-block:: shell
@@ -123,6 +109,8 @@ You can source this file in your ``.bashrc`` or equivalent environment setup fil
.. Warning:: This ``env.sh`` file should always be sourced before running any ``make`` commands. .. 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. .. 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). 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 However, it is recommended that the final ``env.sh`` file sourced is the ``env.sh`` located in the

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

@@ -6,30 +6,28 @@ FPGA-Accelerated Simulation
FireSim 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 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 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. FireSim supports running on Amazon EC2 F1 FPGA-enabled virtual instances and on locally managed Linux machines with FPGAs attached.
In order to simulate your Chipyard design using FireSim, if you have not The rest of this documentation assumes you are running on an Amazon EC2 F1 FPGA-enabled virtual instance.
already, follow the initial EC2 setup instructions as detailed in the `FireSim In order to simuate your Chipyard design using FireSim, make sure to follow the repository setup as described by
documentation <http://docs.fires.im/en/latest/Initial-Setup/index.html>`__. :ref:`Chipyard-Basics/Initial-Repo-Setup:Initial Repository Setup`, if you have not already.
Then clone Chipyard onto your FireSim manager
instance, and setup your Chipyard repository as you would normally.
Next, initalize FireSim as a library in Chipyard by running: Next, initalize FireSim as a library in Chipyard by running:
.. code-block:: shell .. code-block:: shell
# At the root of your chipyard repo # 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-setup.sh`` initializes additional submodules and then invokes
firesim's ``build-setup.sh`` script adding ``--library`` to properly FireSim's ``build-setup.sh`` script adding ``--library`` to properly
initialize FireSim as a library submodule in chipyard. You may run initialize FireSim as a library submodule in Chipyard. You may run
``./sims/firesim/build-setup.sh --help`` to see more options. ``./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 .. code-block:: shell
@@ -45,6 +43,7 @@ and proceed with the rest of the tutorial.
Running your Design in FireSim 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: A FireSim simulation requires 3 additional config fragments: