document buildafi

docs/Advanced-Usage/Manager/Manager-Configuration-Files.rst

@@ -2,8 +2,10 @@ Manager Configuration Files
 ===============================
 
 This page contains a centralized reference for all of the configuration options
-in ``config_runtime.ini``, ``config_build.ini``, ``config_build_recipes.ini``,  and ``config_hwdb.ini``.
+in ``config_runtime.ini``, ``config_build.ini``, ``config_build_recipes.ini``,
+and ``config_hwdb.ini``.
 
+.. _config-runtime:
 
 ``config_runtime.ini``
 --------------------------
@@ -179,6 +181,7 @@ Set this to ``no`` if you want your Run Farm to keep running once the workload
 has completed. Set this to ``yes`` if you want your Run Farm to be TERMINATED
 after the workload has completed and results have been copied off.
 
+.. _config-build:
 
 ``config_build.ini``
 --------------------------
@@ -281,6 +284,7 @@ A list of AWS account IDs that you want to share the AGFIs listed in
 should specify names in the form ``usersname=AWSACCTID``. The left-hand-side is
 just for human readability, only the actual account IDs listed here matter.
 
+.. _config-build-recipes:
 
 ``config_build_recipes.ini``
 --------------------------------
@@ -305,13 +309,15 @@ you made up). Such a section must contain the following fields:
 
 This specifies the basic target design that will be built. Unless you
 are defining a custom system, this should either be ``FireSim``, for
-systems with a NIC, or ``FireSimNoNIC``, for systems without a NIC.
+systems with a NIC, or ``FireSimNoNIC``, for systems without a NIC. These
+are defined in ``firesim/sim/src/main/scala/Targets.scala``.
 
 ``TARGET_CONFIG``
 """""""""""""""""""
 
 This specifies the hardware configuration of the target being simulation. Some
 examples include ``FireSimRocketChipConfig`` and ``FireSimRocketChipQuadCoreConfig``.
+These are defined in ``firesim/sim/src/main/scala/TargetConfigs.scala``.
 
 
 ``PLATFORM_CONFIG``
@@ -319,6 +325,7 @@ examples include ``FireSimRocketChipConfig`` and ``FireSimRocketChipQuadCoreConf
 
 This specifies hardware parameters of the simulation environment - for example,
 selecting between a Latency-Bandwidth Pipe or DDR3 memory models.
+These are defined in ``firesim/sim/src/main/scala/SimConfigs.scala``.
 
 ``instancetype``
 """""""""""""""""""
@@ -337,6 +344,7 @@ you should leave this set to ``None``. This is usually only used if you have
 proprietary RTL that you bake into an FPGA image, but don't want to share with
 users of the simulator.
 
+.. _config-hwdb:
 
 ``config_hwdb.ini``
 ---------------------------

docs/Advanced-Usage/Manager/Manager-Tasks.rst

@@ -28,6 +28,50 @@ configuration files, you'll find backed-up versions in
 ``firesim buildafi``
 ----------------------
 
+This command builds a FireSim AGFI (FPGA Image) from the Chisel RTL for the
+configurations that you specify. The process of defining configurations to
+build is explained in the documentation for :ref:`config-build` and
+:ref:`config-build-recipes`.
+
+For each config, the build process entails:
+
+1. [Locally] Run the elaboration process for your hardware configuration
+
+2. [Locally] FAME-1 transform the design with MIDAS
+
+3. [Locally] Attach simulation models (I/O widgets, memory model, etc.)
+
+4. [Locally] Emit Verilog to run through the AWS FPGA Flow
+
+5. Launch an FPGA Dev AMI build instance for each configuration you want built.
+
+6. [Local/Remote] Prep build instances, copy generated verilog for hardware configuration to buidl instance.
+
+7. [Remote] Run Vivado Synthesis and P&R for the configuration
+
+8. [Local/Remote] Copy back all output generated by Vivado, including the final tar file
+
+9. [Local/AWS Infra] Submit the tar file to the AWS backend for conversion to an AFI
+
+10. [Local] Wait for the AFI to become available, then notify the user of completion by email.
+
+This process happens in parallel for all of the builds you specify. The command
+will exit when all builds are completed (but you will get notified as
+INDIVIDUAL builds complete).
+
+**It is highly recommended that you either run this command in a ``screen`` or use
+``mosh`` to access the build instance. Builds will not finish if you kill the manager.**
+
+When you run a build for a particular configuration, a directory named
+``LAUNCHTIME-CONFIG_TRIPLET-BUILD_NAME`` is created in ``firesim/deploy/results-build/``.
+This directory will contain:
+
+- ``AGFI_INFO``: Describes the state of the AFI being built, while the manager is running. Upon build completion, this contains the AGFI/AFI that was produced, along with its metadata.
+
+- ``cl_firesim:``: This directory is essentially the Vivado project that built the FPGA image, in the state it was in when the Vivado build process completed. This contains reports, stdout from the build, and the final tar file produced by Vivado.
+
+- ``cl_firesim_generated.sv``: This is a copy of the generated verilog used to produce this build. You can also find a copy inside ``cl_firesim``.
+
 
 .. _firesim-launchrunfarm:
 

docs/Advanced-Usage/Manager/Manager-Topology-Definitions.rst

@@ -1,4 +1,4 @@
-Manager Topology Definitions (``user_topology.py``)
-========================
+Manager Network Topology Definitions (``user_topology.py``)
+==================================================================
 
 TODO