From 658e92e951d2368d60c1ed5a2a4f61e7e3b6cf56 Mon Sep 17 00:00:00 2001 From: Colin Schmidt Date: Fri, 1 May 2020 14:23:16 -0700 Subject: [PATCH] [docs] Make the link to initial setup stand out. (#533) * [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 --- docs/Chipyard-Basics/Initial-Repo-Setup.rst | 42 +++++++++-- docs/_static/css/custom.css | 6 ++ docs/conf.py | 3 + docs/index.rst | 82 +-------------------- docs/requirements.txt | 2 +- 5 files changed, 46 insertions(+), 89 deletions(-) create mode 100644 docs/_static/css/custom.css diff --git a/docs/Chipyard-Basics/Initial-Repo-Setup.rst b/docs/Chipyard-Basics/Initial-Repo-Setup.rst index c4732e8a..08930f50 100644 --- a/docs/Chipyard-Basics/Initial-Repo-Setup.rst +++ b/docs/Chipyard-Basics/Initial-Repo-Setup.rst @@ -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. diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 00000000..3fa65d52 --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,6 @@ +.important { + font-size: 175%; +} +.important p{ + font-size: 100%; +} diff --git a/docs/conf.py b/docs/conf.py index f4a3272b..e0accb5e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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. diff --git a/docs/index.rst b/docs/index.rst index 855929cd..d776b353 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 ------------ diff --git a/docs/requirements.txt b/docs/requirements.txt index 2abac52d..4b1565b3 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,4 @@ -Sphinx==1.7.4 +Sphinx==1.8.5 Pygments==2.2.0 sphinx-autobuild sphinx_rtd_theme==0.2.5b1