From 09175f04c4d14268e3decd4e731cc8becdf76732 Mon Sep 17 00:00:00 2001 From: Sagar Karandikar Date: Wed, 28 Jun 2023 22:46:02 +0000 Subject: [PATCH] guide -> tutorial --- .../Running-a-Cluster-Simulation.rst | 14 +++++------ .../Running-a-Single-Node-Simulation.rst | 8 +++---- .../AWS-EC2-F1-Getting-Started/index.rst | 23 +++++++++++-------- .../Initial-Setup/Xilinx-Alveo-Template.rst | 4 ++-- .../Initial-Setup/Xilinx-Vitis-FPGAs.rst | 6 ++--- ...unning-Single-Node-Simulation-Template.rst | 8 +++---- .../Xilinx-Vitis-FPGAs.rst | 6 ++--- 7 files changed, 36 insertions(+), 33 deletions(-) diff --git a/docs/Getting-Started-Guides/AWS-EC2-F1-Getting-Started/Running-Simulations/Running-a-Cluster-Simulation.rst b/docs/Getting-Started-Guides/AWS-EC2-F1-Getting-Started/Running-Simulations/Running-a-Cluster-Simulation.rst index 48de0ede..46a2e3de 100644 --- a/docs/Getting-Started-Guides/AWS-EC2-F1-Getting-Started/Running-Simulations/Running-a-Cluster-Simulation.rst +++ b/docs/Getting-Started-Guides/AWS-EC2-F1-Getting-Started/Running-Simulations/Running-a-Cluster-Simulation.rst @@ -13,7 +13,7 @@ Make sure you are ``ssh`` or ``mosh``'d into your manager instance and have sour Returning to a clean configuration ------------------------------------- -If you already ran the single-node tutorial, let's return to a clean FireSim +If you already ran the single-node getting started guide, let's return to a clean FireSim manager configuration by doing the following: .. code-block:: bash @@ -25,8 +25,8 @@ manager configuration by doing the following: Building target software ------------------------ -If you already built target software during the single-node tutorial, you can -skip to the next part (Setting up the manager configuration). If you haven't followed the single-node tutorial, +If you already built target software during the single-node getting started guide, you can +skip to the next part (Setting up the manager configuration). If you haven't followed the single-node getting started guide, continue with this section. In these instructions, we'll assume that you want to boot the buildroot-based @@ -81,7 +81,7 @@ You'll see other parameters here, like ``run_instance_market``, AWS user, you can see what these do by looking at the :ref:`manager-configuration-files` section. Otherwise, don't change them. -As in the single-node tutorial, we will leave the ``workload:`` mapping +As in the single-node getting started guide, we will leave the ``workload:`` mapping unchanged here, since we do want to run the buildroot-based Linux on our simulated system. The ``terminate_on_completion`` feature is an advanced feature that you can learn more about in the :ref:`manager-configuration-files` @@ -396,7 +396,7 @@ where you can type commands into the simulation and run programs. For example: # -At this point, you can run workloads as you'd like. To finish off this tutorial, +At this point, you can run workloads as you'd like. To finish off this getting started guide, let's poweroff the simulated system and see what the manager does. To do so, in the console of the simulated system, run ``poweroff -f``: @@ -530,7 +530,7 @@ useful for running benchmarks automatically. Note that there is a directory for each simulated node and each simulated switch in the cluster. The :ref:`defining-custom-workloads` section describes this process in detail. -For now, let's wrap-up our tutorial by terminating the ``f1.16xlarge`` instance +For now, let's wrap-up our guide by terminating the ``f1.16xlarge`` instance that we launched. To do so, run: .. code-block:: bash @@ -575,5 +575,5 @@ responsible for ensuring that your instances are terminated appropriately.** Congratulations on running a cluster FireSim simulation! At this point, you can check-out some of the advanced features of FireSim in the sidebar to the left. -Or, hit next to continue to a tutorial that shows you how to build your own +Or, hit next to continue to a guide that shows you how to build your own custom FPGA images. diff --git a/docs/Getting-Started-Guides/AWS-EC2-F1-Getting-Started/Running-Simulations/Running-a-Single-Node-Simulation.rst b/docs/Getting-Started-Guides/AWS-EC2-F1-Getting-Started/Running-Simulations/Running-a-Single-Node-Simulation.rst index f3c0487c..661fba92 100644 --- a/docs/Getting-Started-Guides/AWS-EC2-F1-Getting-Started/Running-Simulations/Running-a-Single-Node-Simulation.rst +++ b/docs/Getting-Started-Guides/AWS-EC2-F1-Getting-Started/Running-Simulations/Running-a-Single-Node-Simulation.rst @@ -16,7 +16,7 @@ Building target software In these instructions, we'll assume that you want to boot Linux on your simulated node. To do so, we'll need to build our FireSim-compatible RISC-V -Linux distro. For this tutorial, we will use a simple buildroot-based +Linux distro. For this guide, we will use a simple buildroot-based distribution. You can do this like so: .. code-block:: bash @@ -372,7 +372,7 @@ where you can type commands into the simulation and run programs. For example: # -At this point, you can run workloads as you'd like. To finish off this tutorial, +At this point, you can run workloads as you'd like. To finish off this guide, let's poweroff the simulated system and see what the manager does. To do so, in the console of the simulated system, run ``poweroff -f``: @@ -453,7 +453,7 @@ automatically copied back to our manager after we run a simulation, which is useful for running benchmarks automatically. The :ref:`defining-custom-workloads` section describes this process in detail. -For now, let's wrap-up our tutorial by terminating the ``f1.2xlarge`` instance +For now, let's wrap-up our guide by terminating the ``f1.2xlarge`` instance that we launched. To do so, run: .. code-block:: bash @@ -499,4 +499,4 @@ Congratulations on running your first FireSim simulation! At this point, you can check-out some of the advanced features of FireSim in the sidebar to the left (for example, we expect that many people will be interested in the ability to automatically run the SPEC17 benchmarks: :ref:`spec-2017`), or you can continue -on with the cluster simulation tutorial. +on with the cluster simulation guide. diff --git a/docs/Getting-Started-Guides/AWS-EC2-F1-Getting-Started/index.rst b/docs/Getting-Started-Guides/AWS-EC2-F1-Getting-Started/index.rst index f172069c..7806d917 100644 --- a/docs/Getting-Started-Guides/AWS-EC2-F1-Getting-Started/index.rst +++ b/docs/Getting-Started-Guides/AWS-EC2-F1-Getting-Started/index.rst @@ -1,21 +1,24 @@ AWS EC2 F1 Getting Started Guide ===================================== -The tutorials that follow this page will guide you through the complete flow for +The getting started guides that follow this page will guide you through the complete flow for getting an example FireSim simulation up and running using AWS EC2 F1. At the end of this -tutorial, you'll have a simulation that simulates a single quad-core Rocket +guide, you'll have a simulation that simulates a single quad-core Rocket Chip-based node with a 4 MB last level cache, 16 GB DDR3, and no NIC. After -this, you can continue to a tutorial that shows you how to simulate -a globally-cycle-accurate cluster-scale FireSim simulation. The final tutorial +this, you can continue to a guide that shows you how to simulate +a globally-cycle-accurate cluster-scale FireSim simulation. The final guide will show you how to build your own FPGA images with customized hardware. -After you complete these tutorials, you can look at the "Advanced Docs" +After you complete these guides, you can look at the "Advanced Docs" in the sidebar to the left. -Here's a high-level outline of what we'll be doing in our AWS EC2 F1 tutorials: +Here's a high-level outline of what we'll be doing in our AWS EC2 F1 getting started guides: #. **Initial Setup/Installation** - a. First-time AWS User Setup: You can skip this if you already have an AWS + a. Background/Terminology: We will discuss some key terminology that will be used in + the rest of the guides. + + #. First-time AWS User Setup: You can skip this if you already have an AWS account/payment method set up. #. Configuring required AWS resources in your account: This sets up the @@ -24,11 +27,11 @@ Here's a high-level outline of what we'll be doing in our AWS EC2 F1 tutorials: #. Setting up a "Manager Instance" from which you will coordinate building and deploying simulations. -#. **Single-node simulation tutorial**: This tutorial guides you through the process of running one simulation on a Run Farm consisting of a single ``f1.2xlarge``, using our pre-built public FireSim AGFIs. +#. **Single-node simulation guide**: This guide walks you through the process of running one simulation on a Run Farm consisting of a single ``f1.2xlarge``, using our pre-built public FireSim AGFIs. -#. **Cluster simulation tutorial**: This tutorial guides you through the process of running an 8-node cluster simulation on a Run Farm consisting of one ``f1.16xlarge``, using our pre-built public FireSim AGFIs and switch models. +#. **Cluster simulation guide**: This guide walks you through the process of running an 8-node cluster simulation on a Run Farm consisting of one ``f1.16xlarge``, using our pre-built public FireSim AGFIs and switch models. -#. **Building your own hardware designs tutorial (Chisel to FPGA Image)**: This tutorial guides you through the full process of taking Rocket Chip RTL and any custom RTL plugged into Rocket Chip and producing a FireSim AGFI to plug into your simulations. This automatically runs Chisel elaboration, FAME-1 Transformation, and the Vivado FPGA flow. +#. **Building your own hardware designs guide (Chisel to FPGA Image)**: This guide walks you through the full process of taking Rocket Chip RTL and any custom RTL plugged into Rocket Chip and producing a FireSim AGFI to plug into your simulations. This automatically runs Chisel elaboration, FAME-1 Transformation, and the Vivado FPGA flow. Generally speaking, you only need to follow step 4 if you're modifying Chisel RTL or changing non-runtime configurable hardware parameters. diff --git a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Initial-Setup/Xilinx-Alveo-Template.rst b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Initial-Setup/Xilinx-Alveo-Template.rst index 3c0164bb..ff95b723 100644 --- a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Initial-Setup/Xilinx-Alveo-Template.rst +++ b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Initial-Setup/Xilinx-Alveo-Template.rst @@ -96,7 +96,7 @@ Now you're ready to continue with other FireSim setup! Setting up your On-Premises Machine =================================== -This tutorial is setting up a single node cluster (i.e. running FPGA bitstream builds and simulations on a single machine) for FireSim use. +This guide is setting up a single node cluster (i.e. running FPGA bitstream builds and simulations on a single machine) for FireSim use. This single machine will serve as the "Manager Machine" that acts as a "head" node that all work will be completed on. Finally, ensure that the |tool_type| tools are sourced in your shell setup (i.e. ``.bashrc`` and or ``.bash_profile``) so that any shell can use the corresponding programs. @@ -237,7 +237,7 @@ your FireSim directory and source this file again with the argument given.** Final Environment Check ----------------------- -Finally, lets verify that the environment variables are correctly setup for the tutorial. Run: +Finally, lets verify that the environment variables are correctly setup for the guide. Run: .. code-block:: bash diff --git a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Initial-Setup/Xilinx-Vitis-FPGAs.rst b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Initial-Setup/Xilinx-Vitis-FPGAs.rst index 4adda39a..c411646f 100644 --- a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Initial-Setup/Xilinx-Vitis-FPGAs.rst +++ b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Initial-Setup/Xilinx-Vitis-FPGAs.rst @@ -13,7 +13,7 @@ Requirements and Installations ------------------------------ We require a base machine that is able to support a |fpga_name| and running Xilinx Vitis. -For the purposes of this tutorial, we assume you are running with a |fpga_name|. +For the purposes of this guide, we assume you are running with a |fpga_name|. Please refer to the minimum system requirements given in the following link: https://docs.xilinx.com/r/en-US/ug1301-getting-started-guide-alveo-accelerator-cards/Minimum-System-Requirements. ``sudo`` access is not needed for the machine except for when the |fpga_name| and corresponding software is installed. @@ -52,7 +52,7 @@ Now you're ready to continue with other FireSim setup! Setting up your On-Premises Machine =================================== -This tutorial is setting up a single node cluster (i.e. running FPGA bitstream builds and simulations on a single machine) for FireSim use. +This guide will walk you through setting up a single node cluster (i.e. running FPGA bitstream builds and simulations on a single machine) for FireSim use. This single machine will serve as the "Manager Machine" that acts as a "head" node that all work will be completed on. Finally, ensure that the |tool_type| tools are sourced in your shell setup (i.e. ``.bashrc`` and or ``.bash_profile``) so that any shell can use the corresponding programs. @@ -193,7 +193,7 @@ your FireSim directory and source this file again with the argument given.** Final Environment Check ----------------------- -Finally, lets verify that the environment variables are correctly setup for the tutorial. Run: +Finally, let's verify that the environment variables are correctly set up for the rest of this guide. Run: .. code-block:: bash diff --git a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Running-Simulations/Running-Single-Node-Simulation-Template.rst b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Running-Simulations/Running-Single-Node-Simulation-Template.rst index 5eabbebb..d2c4df3a 100644 --- a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Running-Simulations/Running-Single-Node-Simulation-Template.rst +++ b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Running-Simulations/Running-Single-Node-Simulation-Template.rst @@ -12,7 +12,7 @@ Building target software In these instructions, we'll assume that you want to boot Linux on your simulated node. To do so, we'll need to build our FireSim-compatible RISC-V -Linux distro. For this tutorial, we will use a simple buildroot-based +Linux distro. For this guide, we will use a simple buildroot-based distribution. You can do this like so: .. code-block:: bash @@ -304,7 +304,7 @@ where you can type commands into the simulation and run programs. For example: # -At this point, you can run workloads as you'd like. To finish off this tutorial, +At this point, you can run workloads as you'd like. To finish off this guide, let's power off the simulated system and see what the manager does. To do so, in the console of the simulated system, run ``poweroff -f``: @@ -381,11 +381,11 @@ If you take a look at the workload output directory given in the manager output What are these files? They are specified to the manager in a configuration file (:gh-file-ref:`deploy/workloads/linux-uniform.json`) as files that we want -automatically copied back from the temporary simulation directory into the ``results-workload`` directory (on our manager machine - which is also ``localhost`` for this tutorial) after we run a simulation, which is +automatically copied back from the temporary simulation directory into the ``results-workload`` directory (on our manager machine - which is also ``localhost`` for this guide) after we run a simulation, which is useful for running benchmarks automatically. The :ref:`defining-custom-workloads` section describes this process in detail. -For now, let's wrap-up our tutorial by terminating the Run Farm that we launched. +For now, let's wrap-up our guide by terminating the Run Farm that we launched. To do so, run: .. code-block:: bash diff --git a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-Vitis-FPGAs.rst b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-Vitis-FPGAs.rst index 7bbd7c95..a526d817 100644 --- a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-Vitis-FPGAs.rst +++ b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-Vitis-FPGAs.rst @@ -11,12 +11,12 @@ #. Setting up a "Manager Machine" from which you will coordinate building and deploying simulations locally. -#. **Single-node simulation tutorial**: This tutorial guides you through the +#. **Single-node simulation guide**: This guide walks you through the process of running one simulation locally consisting of a single |fpga_name|, using our pre-built public FireSim |bit_type| bitstream. -#. **Building your own hardware designs tutorial (Chisel to FPGA Image)**: - This tutorial guides you through the full process of taking Rocket Chip RTL +#. **Building your own hardware designs guide (Chisel to FPGA Image)**: + This guide walks you through the full process of taking Rocket Chip RTL and any custom RTL plugged into Rocket Chip and producing a FireSim bitstream to plug into your simulations. This automatically runs Chisel elaboration, FAME-1 Transformation, and the |build_type| FPGA flow.