restructure the debugging section

docs/Advanced-Usage/Debugging-and-Profiling-on-FPGA/TracerV-with-FlameGraph.rst

@@ -0,0 +1,67 @@
+Profiling with TracerV + FlameGraphs
+=====================================
+
+FireSim can provide a cycle-by-cycle trace of the CPU's architectural state
+over the course of execution. This can be useful for profiling or debugging.
+The tracing functionality is provided by the TracerV widget.
+
+Building a Design with TracerV
+-------------------------------
+
+In all FireChip designs TracerV is generated by default. Other targets can
+enable it by attaching a TracerV Bridge to the RISC-V trace port of one-or-more cores.
+
+Enabling Tracing at Runtime
+----------------------------
+
+To improve simulation preformance, FireSim does not collect data from the
+TracerV Bridge by default. To enable collection, modify the `tracing` section to your
+``config_runtime.ini``.
+
+.. code-block:: ini
+
+    [tracing]
+    enable=yes
+
+Now when you run a workload, a trace output file will be placed in the
+`sim_slot_<slot #>` directory on the F1 instance under the name TRACEFILE.
+
+
+Setting a TracerV Trigger
+---------------------------
+
+Tracing the entirety of a long-running job like a Linux-based workload can
+generate a pretty large image, and you may only care about the state within a
+certain timeframe. 
+Therefore, FireSim allows you to specify a trigger condition for starting and
+stopping trace data collection. FireSim currently provides three possible trigger
+conditions:
+* Simulation cycles: Specify a start cycle and end cycle, based on the simulation cycle count
+* Program Counter (PC) value: Specify a program counter value to start collection, and a program counter
+value in which to end collection.
+* Instruction value: Specify an instruction value upon which to start data collection, and an instruction value
+in which to end collection. This method is particularly valuable for setting the trigger from within the target
+software under evaluation, by using custom "NOP" instructions. As such, one may use the 
+
+
+By default, TracerV does not use a trigger, hence data collection starts at cycle 0 and ends at
+the last cycle of the simulation. To change this, modify the following under
+the "tracing" section of your ``config_runtime.ini``.
+Use the ``selector`` field to choose the type of trigger, and there use the ``start`` and ``end`` fields
+to select the start and end values for the trigger.
+
+.. code-block:: ini
+
+   [tracing]
+   #trigger selector
+   #0 = no trigger
+   #1 = cycle count trigger
+   #2 = program counter trigger
+   #3 = instruction trigger
+   selector=1
+   start=XXXX
+   end=YYYY
+
+
+Interpreting the Trace Result
+------------------------------

docs/Advanced-Usage/Debugging-and-Profiling-on-FPGA/index.rst

@@ -0,0 +1,16 @@
+Debugging and Profiling on the FPGA
+======================================
+
+This section describes methods of debugging and profiling target designs and
+simulation components *once you have a FireSim simulation running on an FPGA*.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Debugging and Profiling on the FPGA:
+
+   Debugging-Hardware-Using-ILA.rst
+   TracerV.rst
+   DESSERT.rst
+   printf-synthesis.rst
+   AutoCounter.rst

docs/Advanced-Usage/Debugging-in-Software/index.rst

@@ -0,0 +1,12 @@
+Debugging in Software
+=========================
+
+This section describes methods of debugging the target design and the
+simulation in FireSim, *before running on the FPGA*.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Debugging in Software:
+
+   RTL-Simulation.rst

docs/Advanced-Usage/Debugging/index.rst

@@ -1,16 +0,0 @@
-Debugging
-================
-
-This section describes methods of debugging the target design and the simulation in FireSim.
-
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Debugging:
-
-   RTL-Simulation.rst
-   Debugging-Hardware-Using-ILA.rst
-   TracerV.rst
-   DESSERT.rst
-   printf-synthesis.rst
-   AutoCounter.rst

docs/index.rst

@@ -25,7 +25,8 @@ New to FireSim? Jump to the :ref:`firesim-basics` page for more info.
    Advanced-Usage/Manager/index
    Advanced-Usage/Workloads/index
    Advanced-Usage/Generating-Different-Targets.rst
-   Advanced-Usage/Debugging/index
+   Advanced-Usage/Debugging-in-Software/index
+   Advanced-Usage/Debugging-and-Profiling-on-FPGA/index
    Advanced-Usage/Supernode.rst
    Advanced-Usage/Miscellaneous-Tips.rst
    Advanced-Usage/FAQs.rst