check in CI if example outputs used in docs are up to date

.github/scripts/check-docs-generated-components.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+
+from fabric.api import *
+
+from common import manager_fsim_dir, set_fabric_firesim_pem
+
+def run_docs_generated_components_check():
+    """ Runs checks to make sure generated components of docs have been
+    updated. """
+
+    with cd(manager_fsim_dir), prefix('source env.sh'):
+        run("cd deploy && diff -q config_runtime.yaml ../docs/Running-Simulations-Tutorial/DOCS_EXAMPLE_config_runtime.yaml")
+        run("cd deploy && firesim --help &> TEMP_HELP_OUTPUT && diff -q TEMP_HELP_OUTPUT ../docs/Advanced-Usage/Manager/HELP_OUTPUT")
+
+if __name__ == "__main__":
+    set_fabric_firesim_pem()
+    execute(run_docs_generated_components_check, hosts=["localhost"])

.github/workflows/firesim-run-tests.yml

@@ -98,6 +98,9 @@ jobs:
         uses: ./.github/actions/initialize-manager
         with:
           max-runtime-hours: 10
+      - name: Check docs components that require manual re-generation (e.g. config_runtime.yaml example, help output)
+        run: ./.github/scripts/check-docs-generated-components.py
+        continue-on-error: true
       - name: Initial Scala compilation
         uses: ./.github/actions/initial-scala-compile
       - name: Catch potentially orphaned manager

docs/Running-Simulations-Tutorial/DOCS_EXAMPLE_config_runtime.yaml

@@ -0,0 +1,106 @@
+# RUNTIME configuration for the FireSim Simulation Manager
+# See https://docs.fires.im/en/stable/Advanced-Usage/Manager/Manager-Configuration-Files.html for documentation of all of these params.
+
+run_farm:
+  base_recipe: run-farm-recipes/aws_ec2.yaml
+  recipe_arg_overrides:
+    # tag to apply to run farm hosts
+    run_farm_tag: mainrunfarm
+    # enable expanding run farm by run_farm_hosts given
+    always_expand_run_farm: true
+    # minutes to retry attempting to request instances
+    launch_instances_timeout_minutes: 60
+    # run farm host market to use (ondemand, spot)
+    run_instance_market: ondemand
+    # if using spot instances, determine the interrupt behavior (terminate, stop, hibernate)
+    spot_interruption_behavior: terminate
+    # if using spot instances, determine the max price
+    spot_max_price: ondemand
+    # default location of the simulation directory on the run farm host
+    default_simulation_dir: /home/centos
+
+    # run farm hosts to spawn: a mapping from a spec below (which is an EC2
+    # instance type) to the number of instances of the given type that you
+    # want in your runfarm.
+    run_farm_hosts_to_use:
+      - f1.16xlarge: 0
+      - f1.4xlarge: 0
+      - f1.2xlarge: 0
+      - m4.16xlarge: 0
+      - z1d.3xlarge: 0
+      - z1d.6xlarge: 0
+      - z1d.12xlarge: 0
+
+metasimulation:
+  metasimulation_enabled: false
+  # vcs or verilator. use vcs-debug or verilator-debug for waveform generation
+  metasimulation_host_simulator: verilator
+  # plusargs passed to the simulator for all metasimulations
+  metasimulation_only_plusargs: "+fesvr-step-size=128 +dramsim +max-cycles=100000000"
+  # plusargs passed to the simulator ONLY FOR vcs metasimulations
+  metasimulation_only_vcs_plusargs: "+vcs+initreg+0 +vcs+initmem+0"
+
+target_config:
+    # Set topology: no_net_config to run without a network simulation
+    topology: example_8config
+    no_net_num_nodes: 2
+    link_latency: 6405
+    switching_latency: 10
+    net_bandwidth: 200
+    profile_interval: -1
+
+    # This references a section from config_hwdb.yaml for fpga-accelerated simulation
+    # or from config_build_recipes.yaml for metasimulation
+    # In homogeneous configurations, use this to set the hardware config deployed
+    # for all simulators
+    default_hw_config: firesim_rocket_quadcore_nic_l2_llc4mb_ddr3
+
+    # Advanced: Specify any extra plusargs you would like to provide when
+    # booting the simulator (in both FPGA-sim and metasim modes). This is
+    # a string, with the contents formatted as if you were passing the plusargs
+    # at command line, e.g. "+a=1 +b=2"
+    plusarg_passthrough: ""
+
+tracing:
+    enable: no
+
+    # Trace output formats. Only enabled if "enable" is set to "yes" above
+    # 0 = human readable; 1 = binary (compressed raw data); 2 = flamegraph (stack
+    # unwinding -> Flame Graph)
+    output_format: 0
+
+    # Trigger selector.
+    # 0 = no trigger; 1 = cycle count trigger; 2 = program counter trigger; 3 =
+    # instruction trigger
+    selector: 1
+    start: 0
+    end: -1
+
+autocounter:
+    read_rate: 0
+
+workload:
+    workload_name: linux-uniform.json
+    terminate_on_completion: no
+    suffix_tag: null
+
+host_debug:
+    # When enabled (=yes), Zeros-out FPGA-attached DRAM before simulations
+    # begin (takes 2-5 minutes).
+    # In general, this is not required to produce deterministic simulations on
+    # target machines running linux. Enable if you observe simulation non-determinism.
+    zero_out_dram: no
+    # If disable_synth_asserts: no, simulation will print assertion message and
+    # terminate simulation if synthesized assertion fires.
+    # If disable_synth_asserts: yes, simulation ignores assertion firing and
+    # continues simulation.
+    disable_synth_asserts: no
+
+synth_print:
+    # Start and end cycles for outputting synthesized prints.
+    # They are given in terms of the base clock and will be converted
+    # for each clock domain.
+    start: 0
+    end: -1
+    # When enabled (=yes), prefix print output with the target cycle at which the print was triggered
+    cycle_prefix: yes

docs/Running-Simulations-Tutorial/Running-a-Single-Node-Simulation.rst

@@ -48,7 +48,7 @@ all of the parameters in the :ref:`manager-configuration-files` section.
 If you open up this file, you will see the following default config (assuming
 you have not modified it):
 
-.. include:: /../deploy/sample-backup-configs/sample_config_runtime.yaml
+.. include:: DOCS_EXAMPLE_config_runtime.yaml
    :code: yaml
 
 We'll need to modify a couple of these lines.