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

[docs] Make the link to initial setup stand out. (#533)

Browse Source 
* [docs] Make the link to initial setup stand out.
* [docs] Merge the two quick starts
* More descriptive text about the setup link
Co-authored-by: alonamid <alonamid@eecs.berkeley.edu>
This commit is contained in:
Colin Schmidt
2020-05-01 14:23:16 -07:00
committed by GitHub
parent 02367022b0
commit 658e92e951
5 changed files with 46 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -23,10 +23,10 @@ In Ubuntu/Debian-based platforms (Ubuntu), we recommend installing the following
.. 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).
Checking out the sources
------------------------
Setting up the Chipyard Repo
-------------------------------------------
After cloning this repo, you will need to initialize all of the submodules.
Start by fetching Chipyard's sources. Run:
.. code-block:: shell
@@ -34,6 +34,8 @@ After cloning this repo, you will need to initialize all of the submodules.
cd chipyard
./scripts/init-submodules-no-riscv-tools.sh
This will initialize and checkout all of the necessary git submodules.
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.
@@ -46,15 +48,41 @@ The `toolchains` directory contains toolchains that include a cross-compiler too
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``.
.. code-block:: shell
./scripts/build-toolchains.sh riscv-tools # for a normal risc-v toolchain
# OR
./scripts/build-toolchains.sh esp-tools # for a modified risc-v toolchain with Hwacha vector instructions
.. 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.
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.
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:
.. code-block:: shell
source ./env.sh
These variables need to be set for the ``make`` system to work properly.
What's Next?
-------------------------------------------
This depends on what you are planning to do with Chipyard.
* If you intend to run a simulation of one of the vanilla Chipyard examples, go to :ref:`sw-rtl-sim-intro` and follow the instructions.
* If you intend to run a simulation of a custom Chipyard SoC Configuration, go to :ref:`Simulating A Custom Project` and follow the instructions.
* If you intend to run a full-system FireSim simulation, go to :ref:`firesim-sim-intro` and follow the instructions.
* If you intend to add a new accelerator, go to :ref:`customization` and follow the instructions.
* If you want to learn about the structure of Chipyard, go to :ref:`chipyard-components`.
* If you intend to change the generators (BOOM, Rocket, etc) themselves, see :ref:`generator-index`.
* If you intend to run a tutorial VLSI flow using one of the Chipyard examples, go to :ref:`tutorial` and follow the instructions.
* If you intend to build a chip using one of the vanilla Chipyard examples, go to :ref:`build-a-chip` and follow the instructions.

6
docs/_static/css/custom.css vendored Normal file
View File

@@ -0,0 +1,6 @@
.important {
font-size: 175%;
}
.important p{
font-size: 100%;
}

3
docs/conf.py
View File

@@ -106,6 +106,9 @@ html_theme_options = {
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
html_css_files = [
'css/custom.css',
]
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.

82
docs/index.rst
View File

@@ -10,89 +10,9 @@ Welcome to Chipyard's documentation!
Chipyard is a framework for designing and evaluating full-system hardware using agile teams.
It is composed of a collection of tools and libraries designed to provide an integration between open-source and commercial tools for the development of systems-on-chip.
New to Chipyard? Jump to the :ref:`Chipyard Basics` page for more info.
Quick Start
===============================
.. IMPORTANT:: **New to Chipyard?** Jump to the :ref:`Initial Repository Setup` page for setup instructions.
System Requirements
-------------------------------------------
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:: Working under Windows is not recommended.
Setting up the Chipyard Repo
-------------------------------------------
Start by fetching Chipyard's sources. Run:
.. code-block:: shell
git clone https://github.com/ucb-bar/chipyard.git
cd chipyard
./scripts/init-submodules-no-riscv-tools.sh
This will initialize and checkout all of the necessary git submodules.
Installing Dependencies
-------------------------------------------
Installing the recommended dependencies on Ubuntu/Debian-based platforms:
.. code-block:: shell
./scripts/ubuntu-req.sh
Installing the recommended dependencies on CentOS-based platforms:
.. code-block:: shell
./scripts/centos-req.sh
Installing the RISC-V Tools
-------------------------------------------
We need to install the RISC-V toolchain in order to be able to run RISC-V programs using the Chipyard infrastructure.
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``.
To build the toolchains, you should run:
.. code-block:: shell
./scripts/build-toolchains.sh
.. 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.
Finally, set up Chipyard's environment variables and put the newly built toolchain on your path:
.. code-block:: shell
source ./env.sh
What's Next?
-------------------------------------------
This depends on what you are planning to do with Chipyard.
* If you intend to run a simulation of one of the vanilla Chipyard examples, go to :ref:`sw-rtl-sim-intro` and follow the instructions.
* If you intend to run a simulation of a custom Chipyard SoC Configuration, go to :ref:`Simulating A Custom Project` and follow the instructions.
* If you intend to run a full-system FireSim simulation, go to :ref:`firesim-sim-intro` and follow the instructions.
* If you intend to add a new accelerator, go to :ref:`customization` and follow the instructions.
* If you want to learn about the structure of Chipyard, go to :ref:`chipyard-components`.
* If you intend to change the generators (BOOM, Rocket, etc) themselves, see :ref:`generator-index`.
* If you intend to run a tutorial VLSI flow using one of the Chipyard examples, go to :ref:`tutorial` and follow the instructions.
* If you intend to build a chip using one of the vanilla Chipyard examples, go to :ref:`build-a-chip` and follow the instructions.
Getting Help
------------

2
docs/requirements.txt
View File

@@ -1,4 +1,4 @@
Sphinx==1.7.4
Sphinx==1.8.5
Pygments==2.2.0
sphinx-autobuild
sphinx_rtd_theme==0.2.5b1