[SQUASH ME] Cleaned Up Figure and Wording

Author: AlexandreSinger

doc/src/tutorials/timing_analysis/index.rst

@@ -15,14 +15,14 @@ multi-clock timing analysis, which tools like OpenSTA have better support for.
 
 .. figure:: timing_analysis_design_cycle.png
 
-    Timing analysis design cycle flow diagram.
+    Post-implementation timing analysis design cycle.
 
-A user design cycle which would use this would perform the following steps:
-    1. Run VPR with the timing commands it can support.
+A user design cycle which would use post-implementation timing analysis could perform the following:
+    1. Run VPR with the timing commands it can support (simplified constraints).
     2. Perform timing analysis on the resulting netlist using OpenSTA with
        more complex timing commands.
-    3. Modify the user design to meet the complex timing constraints.
-    4. Repeat.
+    3. The user can then modify the design to meet the complex timing constraints based on the timing report produced by OpenSTA.
+    4. The design can then be fed back into VPR and the process can repeat until all constraints are met.
 
 Generating the Post-Implementation Netlist for STA
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -47,7 +47,7 @@ directory for convenience:
 
 .. note:: Replace :term:`$VTR_ROOT` with the root directory of the VTR source tree
 
-To perform timing analysis externally to VTR, we will need to create an SDC file
+To perform timing analysis externally to VTR, we will need to provide an SDC file
 which will contain the timing constraints on the clocks and I/Os in the circuit.
 For this tutorial, we will use the following ``clma.sdc`` file:
 
@@ -81,10 +81,10 @@ for timing analysis using VPR.
 
 In this command, we provide the architecture, circuit, the channel width, and
 the SDC file. The other four commands are what generate the necessary netlist
-files for timing simulation:
+files for timing analysis:
  * ``--gen_post_synthesis_netlist on``: This will generate the post-implementation netlist as a Verilog file.
- * ``--gen_post_implementation_sdc on``: This will have VPR generate a new SDC file which contains extra timing information used from proper timing analysis.
- * ``--post_synth_netlist_unconn_inputs gnd``: For timing analysis with OpenSTA we want to be explicit about how we handle unconnected signal ports. Here we just ground them for simplicity.
+ * ``--gen_post_implementation_sdc on``: This will have VPR generate a new SDC file which contains extra timing information based on how VPR implemented the design.
+ * ``--post_synth_netlist_unconn_inputs gnd``: For timing analysis with OpenSTA, we should be explicit about how we handle unconnected signal ports. Here we just ground them for simplicity.
  * ``--post_synth_netlist_module_parameters off``: OpenSTA does not allow parameters to be used in the netlist. This command tells VPR to generate a netlist without using parameters.
 
 Once VPR has completed, we should see the generated Verilog netlist, SDF file, and SDC file:
@@ -98,11 +98,11 @@ Once VPR has completed, we should see the generated Verilog netlist, SDF file, a
 Performing Timing Analysis using OpenSTA
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To perform static timing analysis for this tutorial, we will be using OpenSTA.
-Other STA tools can be used, they may use slightly different commands.
+To perform static timing analysis for this tutorial, we will be using OpenSTA (https://github.com/parallaxsw/OpenSTA ).
+Other STA tools can be used, however they may use slightly different commands.
 
 First, install OpenSTA onto your system. Building from source is a good option,
-using the following instructions:
+which can be done using the following instructions:
 https://github.com/parallaxsw/OpenSTA?tab=readme-ov-file#build-from-source
 
 After OpenSTA is installed, we can perfrom static timing analysis on the post-implementation
@@ -119,24 +119,24 @@ It is easiest to write a ``sdf_delays.tcl`` file to setup and configure the timi
     # an SDF file. This contains descriptions of the timing arcs of the primitives
     # in the circuit.
     read_liberty $VTR_ROOT/vtr_flow/primitives.lib
-    
+
     # Read the post-implementation netlist generated by VPR.
     read_verilog top_post_synthesis.v
-    
+
     # Link the top-level design.
     link_design top
-    
+
     # Read the post-synthesis SDF file.
     read_sdf top_post_synthesis.sdf
-    
+
     # Read the SDC commands generated by VPR.
     read_sdc top_post_synthesis.sdc
-    
-    # Report the setup and hold timing checks using OpenSTA and write to a file.
-    report_checks -group_path_count 100 -path_delay max > open_sta_report_timing.setup.rpt
-    report_checks -group_path_count 100 -path_delay min > open_sta_report_timing.hold.rpt
 
-    # Report the minimum period of the clock and the fmax.
+    # Report the setup and hold timing checks using OpenSTA and write them to files.
+    report_checks -group_path_count 100 -digits 3 -path_delay max > open_sta_report_timing.setup.rpt
+    report_checks -group_path_count 100 -digits 3 -path_delay min > open_sta_report_timing.hold.rpt
+
+    # Report the minimum period of the clockis and their fmax.
     report_clock_min_period
 
     # Exit OpenSTA's TCL terminal.

doc/src/tutorials/timing_analysis/timing_analysis_design_cycle.png

@@ -6,11 +6,15 @@
  *        post-synthesis netlist (from VTR) into OpenSTA.
  *
  * This file contains just enough information to allow OpenSTA to use a provided
- * SDF file for timing analysis of the netlist. It likely is missing primitives
- * from some architectures.
+ * SDF file for timing analysis of the netlist.
+ *
+ * This file only defines the primitives that VPR defines as "library models".
+ * This includes LUTs (.names) and Flip-Flops (.latch). For user models (the
+ * models defined in the "models" section of the architecture description file),
+ * one should create another liberty file.
  */
 
-library (Skeleton) {
+library (VTRPrimitives) {
 
     /* General Attributes */
     delay_model             		: table_lookup;
@@ -29,7 +33,7 @@ library (Skeleton) {
     output_threshold_pct_fall     	: 50.00 ;
     output_threshold_pct_rise     	: 50.00 ;
 
-    /* Bus types used for the LUT cells to allow their inputs to be an arrays.*/
+    /* Bus types used for the LUT cells to allow their inputs to be arrays.*/
     type (BUS4) {
         base_type: array;
         data_type: bit;
@@ -73,7 +77,16 @@ library (Skeleton) {
         bit_to: 0;
     }
 
-    /* FPGA interconnect module. Modelled after the timing model of a buffer */
+    /**
+     * @brief FPGA interconnect module. This cell acts as a wire in the post-
+     *        implementation netlist to add delays on connections between
+     *        primitives (due to routing delays).
+     *
+     *  INPUTS:
+     *      datain
+     *  OUPUTS:
+     *      dataout
+     */
     cell (fpga_interconnect) {
         pin (datain) {
             direction: input;
@@ -102,7 +115,19 @@ library (Skeleton) {
         }
     }
 
-    /* 4-bit LUT module. This module takes the mask as an input, and the output is a function of the mask and the input pins.*/
+    /**
+     * @brief 4-input LUT module.
+     *
+     *  INPUTS:
+     *      in:
+     *          The input pins of the LUT, as an array.
+     *      mask:
+     *          The LUT mask that defines the output of the LUT as a function
+     *          of the input. mask[0] is the output if all the inputs are 0, and
+     *          mask[2^k - 1] is the output if all the inputs are 1.
+     *  OUPUTS:
+     *      out
+     */
     cell (LUT_4) {
         bus (mask) {
             bus_type: "BUS16";
@@ -136,7 +161,19 @@ library (Skeleton) {
         }
     }
 
-    /* 5-bit LUT module. This module takes the mask as an input, and the output is a function of the mask and the input pins.*/
+    /**
+     * @brief 5-input LUT module.
+     *
+     *  INPUTS:
+     *      in:
+     *          The input pins of the LUT, as an array.
+     *      mask:
+     *          The LUT mask that defines the output of the LUT as a function
+     *          of the input. mask[0] is the output if all the inputs are 0, and
+     *          mask[2^k - 1] is the output if all the inputs are 1.
+     *  OUPUTS:
+     *      out
+     */
     cell (LUT_5) {
         bus (mask) {
             bus_type: "BUS32";
@@ -170,7 +207,19 @@ library (Skeleton) {
         }
     }
 
-    /* 6-bit LUT module. This module takes the mask as an input, and the output is a function of the mask and the input pins.*/
+    /**
+     * @brief 6-input LUT module.
+     *
+     *  INPUTS:
+     *      in:
+     *          The input pins of the LUT, as an array.
+     *      mask:
+     *          The LUT mask that defines the output of the LUT as a function
+     *          of the input. mask[0] is the output if all the inputs are 0, and
+     *          mask[2^k - 1] is the output if all the inputs are 1.
+     *  OUPUTS:
+     *      out
+     */
     cell (LUT_6) {
         bus (mask) {
             bus_type: "BUS64";
@@ -204,7 +253,21 @@ library (Skeleton) {
         }
     }
 
-    /* D-flip-flop module. Modelled after the timing model of a standard DFF */
+    /**
+     * @brief D-Flip-Flop module.
+     *
+     *  INPUTS:
+     *      D:
+     *          The input of the DFF, which will get latched on the rising clock
+     *          edge.
+     *      clock:
+     *          The clock signal for the DFF.
+     *  OUPUTS:
+     *      Q:
+     *          The current value stored in the latch.
+     *      QN:
+     *          The inverse of the current value stored in the latch.
+     */
     cell (DFF) {
         ff (IQ, IQN) {
             next_state: "D";