Merge remote-tracking branch 'origin/db-doc-edits' into doc-updates-new-2

docs/FireSim-Basics.rst

@@ -64,13 +64,22 @@ Background/Terminology
 -  **Run Farm**: These are F1 (and M4) instances that the manager
    automatically launches and deploys simulations onto.
 
+To disambiguate between the computers being simulated and the computers doing the simulating, we define:
+
+-  **Target**: The design and environment under simulation. Generally, a
+   network of one or more multi-core RISC-V microprocessors.
+-  **Host**: The computers executing the FireSim simulation -- the Run Farm.
+
+We frequently prefix words with these terms. For example, software can run
+on the simulated RISCV system (*target*-software) or on a host x86 machine (*host*-software).
+
 Using FireSim/The FireSim Workflow
 -------------------------------------
 
 The tutorials that follow this page will guide you through the complete flow for
 getting an example FireSim simulation up and running. At the end of this
 tutorial, you'll have a simulation that simulates a single quad-core Rocket
-Chip-based node with a 4 MB LLC, 16 GB DDR3, and no NIC. After this, you'll
+Chip-based node with a 4 MB last level cache, 16 GB DDR3, and no NIC. After this, you'll
 have the option to continue on to a tutorial that describes how to simulate
 many of these single-node simulations in parallel or how to simulate
 a globally-cycle-accurate cluster-scale FireSim simulation. The final tutorial
@@ -87,7 +96,7 @@ Here's a high-level outline of what we'll be doing:
        This sets up the appropriate VPCs/subnets/security groups required to
        run FireSim.
     c. Setting up a "Manager Instance" from which you will coordinate
-       building/deploying simulations.
+       building and deploying simulations.
 
 2. Single-node simulation tutorial: This tutorial guides you through the process of running one simulation on a single ``f1.2xlarge``, using our pre-built public FireSim AGFIs.
 
@@ -103,11 +112,10 @@ Here's a high-level outline of what we'll be doing:
 4. Building your own hardware designs tutorial (Chisel -> FPGA Image)
 
     a. Building a FireSim AFI: Running a build process that goes from Chisel -> Verilog and then
-       Verilog -> AFI/AGFI (FPGA Image). This process automatically creates "Build Farm" instances,
+       Verilog -> AFI/AGFI (Amazon's FPGA Image). This process automatically creates "Build Farm" instances,
-       runs builds on them, and terminates them when AGFI completion is
+       runs builds on them, and terminates them once the AGFIs has been generated.
-       completed. All Vivado reports/outputs are copied onto your Manager
+       All Vivado reports/outputs are copied onto your Manager
-       Instance before they are terminated.
+       Instance before Build Farm instances are terminated.
-
 
 Generally speaking, you only need to follow step 4 if you're modifying
 Chisel RTL or changing non-runtime configurable hardware parameters.

docs/Initial-Setup/Configuring-Required-Infrastructure-in-Your-AWS-Account.rst

@@ -3,7 +3,7 @@ Configuring Required Infrastructure in Your AWS Account
 
 Once we have an AWS Account setup, we need to perform some advance setup
 of resources on AWS. You will need to follow these steps even if you
-already had an AWS account, these are FireSim-specific.
+already had an AWS account as these are FireSim-specific.
 
 Select a region
 ~~~~~~~~~~~~~~~
@@ -56,7 +56,7 @@ your local machine, we will spin up a very cheap ``t2.nano`` instance to
 run a series of one-time aws configuration commands to setup our AWS
 account for FireSim. At the end of these instructions, we'll terminate
 the ``t2.nano`` instance. If you happen to already have ``boto3`` and
-the AWS CLI installed on your local machine, you can use that instead.
+the AWS CLI installed on your local machine, you can do this locally.
 
 Launch a ``t2.nano`` by following these instructions:
 
@@ -82,7 +82,7 @@ SSH into the ``t2.nano`` like so:
 
     ssh -i firesim.pem ec2-user@INSTANCE_PUBLIC_IP
 
-Which should present you with:
+Which should present you with something like:
 
 ::
 
@@ -127,6 +127,8 @@ At this point, we are finished with the general account configuration.
 You should terminate the t2.nano instance you created, since we do not
 need it anymore (and it shouldn't contain any important data).
 
+.. _ami-subscription:
+
 Subscribe to the AWS FPGA Developer AMI
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/Initial-Setup/Setting-up-your-Manager-Instance.rst

@@ -4,21 +4,14 @@ Setting up your Manager Instance
 Launching a "Manager Instance"
 ------------------------------
 
-Now, we need to launch a "Manager Instance" that essentially acts as a
+Now, we need to launch a "Manager Instance" that acts as a
-"head" node that we will actually ``ssh`` or ``mosh`` into to work from.
+"head" node that we will ``ssh`` or ``mosh`` into to work from.
-We will deploy the heavy lifting to separate ``c4.4xlarge`` and
+Since we will deploy the heavy lifting to separate ``c4.4xlarge`` and
-``f1`` instances later, this can be a relatively cheap instance. In this guide
+``f1`` instances later, the Manager Instance can be a relatively cheap instance. In this guide, however,
-however, we will assume that our manager instance is a ``c4.4xlarge`` instance,
+we will use a ``c4.4xlarge``,
-running the AWS FPGA Developer AMI (the specific version listed below). The
+running the AWS FPGA Developer AMI (be sure to subscribe if you have not done so. See :ref:`ami-subscription`).
-instructions below will guide you through the process of getting this instance
-up and running.
 
-First, we need to subscribe to the Amazon FPGA Developer AMI (which is free).
+Head to the `EC2 Management
-To do so, make sure you are logged into your AWS account, then visit: https://aws.amazon.com/marketplace/pp/B06VVYBLZZ/
-
-On this page, click "Continue to Subscribe" and then "Accept Terms" on the following page.
-
-Next, head to the `EC2 Management
 Console <https://console.aws.amazon.com/ec2/v2/home>`__. In the top
 right corner, ensure that the correct region is selected.
 
@@ -53,7 +46,7 @@ To launch a manager instance, follow these steps:
 
 5. On the next page ("Add Storage"), increase the size of the root EBS
    volume to ~300GB. The default of 150GB can quickly become tight as
-   you have large Vivado reports/outputs, large waveforms, XSim outputs,
+   you accumulate large Vivado reports/outputs, large waveforms, XSim outputs,
    and large root filesystems for simulations. You can get rid of the
    small (5GB) secondary volume that is added by default.
 6. You can skip the "Add Tags" page, unless you want tags.
@@ -83,13 +76,13 @@ In either case, ``ssh`` into your instance and wait until the
     machine launch script started
     machine launch script completed!
 
-Once this line appears, you should exit and re-``ssh`` into the system. If you want
+Once this line appears, exit and re-``ssh`` into the system. If you want
 to use ``mosh``, ``mosh`` back into the system.
 
 Key Setup, Part 2
 ~~~~~~~~~~~~~~~~~
 
-Now that our manager instance is started, copy the key that you
+Now that our manager instance is started, copy the private key that you
 downloaded from AWS earlier (``firesim.pem``) to ``~/firesim.pem`` on
 your manager instance. This step is required to give the manager access
 to the instances it launches for you.
@@ -97,11 +90,7 @@ to the instances it launches for you.
 Setting up the FireSim Repo
 ---------------------------
 
-Since FireSim is not yet public, you must setup another set of ``ssh``
+We're finally ready to fetch FireSim's sources. Run:
-keys to use with your GitHub account with ``ssh-keygen``. Make sure you
-**DO NOT overwrite** ``~/firesim.pem``. ``ssh-keygen`` will put the new
-key it generates in ``~/.ssh/id_rsa[.pub]``, which is fine. Once you
-have done that, run:
 
 ::
 
@@ -145,4 +134,4 @@ send email notifications upon FPGA build completion and optionally for
 workload completion. You can leave this blank if you do not wish to receive any
 notifications, but this is not recommended.
 
-Hit Next to continue to the next page.
+Now you're ready to launch FireSim simulations! Hit Next to learn how to run single-node simulations.