OpenFPGA/docs/source/tutorials/arch_modeling/spypads_tutorial.rst

Creating Spypads Using XML Syntax
=================================

Introduction
~~~~~~~~~~~~

**In this tutorial, we will**
   - Show the XML syntax for global outputs
   - Showcase an example with spypads
   - Modify an existing architecture to incorporate spypads
   - Verify correctness through GTKWave

Through this tutorial, we will show how to create spypads in OpenFPGA.

Spypads are physical output pins on a FPGA chip through which you can read out internal signals when doing silicon-level debugging. The XML syntax for spypads and other 
global signals can be found on our :ref:`circuit_library` documentation page.

To create a spypad, the ``port type`` needs to be set to **output** and ``is_global`` and ``is_io`` need to be set to **true**:

.. code-block:: xml

   <port type="output" is_global="true" is_io="true"/>

When the port is syntactically correct, the outputs are independently wired from different instances to separated FPGA outputs and would physically look like :ref:`fig_gpout_ports` 



Pre-Built Spypads
~~~~~~~~~~~~~~~~~

An OpenFPGA architecture file that contains spypads and has a task that references it is the `k6_frac_N10_adder_register_scan_chain_depop50_spypad_40nm_openfpga.xml <https://github.com/lnis-uofu/OpenFPGA/blob/tutorials/openfpga_flow/openfpga_arch/k6_frac_N10_adder_register_scan_chain_depop50_spypad_40nm_openfpga.xml>`_ 
file. We can view ``k6_frac_N10_adder_register_scan_chain_depop50_spypad_40nm_openfpga.xml`` by entering the following command at the root directory of OpenFPGA:

.. code-block:: bash

   emacs openfpga_flow/openfpga_arch/k6_frac_N10_adder_register_scan_chain_depop50_spypad_40nm_openfpga.xml

In this architecture file, the output ports of a 6-input Look-Up Table (LUT) are defined as spypads using the XML syntax ``is_global`` and ``is_io``. As a result, all of the outputs from the 6-input LUT will be visible in the top-level module. The output ports to the 6-input LUT are declared from **LINE181** to **LINE183** and belong to the ``frac_lut6_spypad`` ``circuit_model`` that begins at **LINE172**.

.. code-block:: xml
   
   <circuit_model type="lut" name="frac_lut6_spypad" prefix="frac_lut6_spypad" dump_structural_verilog="true">
      <design_technology type="cmos" fracturable_lut="true"/>
      <input_buffer exist="true" circuit_model_name="INVTX1"/>
      <output_buffer exist="true" circuit_model_name="INVTX1"/>
      <lut_input_inverter exist="true" circuit_model_name="INVTX1"/>
      <lut_input_buffer exist="true" circuit_model_name="buf4"/>
      <lut_intermediate_buffer exist="true" circuit_model_name="buf4" location_map="-1-1-"/>
      <pass_gate_logic circuit_model_name="TGATE"/>
      <port type="input" prefix="in" size="6" tri_state_map="----11" circuit_model_name="OR2"/>
      LINE181 <port type="output" prefix="lut4_out" size="4" lut_frac_level="4" lut_output_mask="0,1,2,3" is_global="true" is_io="true"/>
      LINE182 <port type="output" prefix="lut5_out" size="2" lut_frac_level="5" lut_output_mask="0,1" is_global="true" is_io="true"/>
      LINE183 <port type="output" prefix="lut6_out" size="1" lut_output_mask="0" is_global="true" is_io="true"/>
      <port type="sram" prefix="sram" size="64"/>
      <port type="sram" prefix="mode" size="2" mode_select="true" circuit_model_name="DFFR" default_val="1"/>
   </circuit_model>

The spypads are instantiated in the top-level verilog module ``fpga_top.v``. ``fpga_top.v`` is automatically generated when we run our task from the OpenFPGA root
directory. However, we need to modify the task configuration file to run the **full testbench** instead of the **formal testbench** to view the spypads' waveforms in 
GTKWave. 

.. note:: To read about the differences between the **formal testbench** and the **full testbench**, please visit our page on testbenches: :ref:`testbench`.

To open the task configuration file, run this command from the root directory of OpenFPGA:

.. code-block:: bash

   emacs openfpga_flow/tasks/fpga_verilog/spypad/config/task.conf

The last line of the task configuration file (**LINE44**) sets the **formal testbench** to be the desired testbench. To use the **full testbench**, comment out **LINE44**.
The file will look like this when finished:

.. code-block:: python
   :linenos:
   
   # = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
   # Configuration file for running experiments
   # = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
   # timeout_each_job : FPGA Task script splits fpga flow into multiple jobs
   # Each job execute fpga_flow script on combination of architecture & benchmark
   # timeout_each_job is timeout for each job
   # = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

   [GENERAL]
   run_engine=openfpga_shell
   power_tech_file = ${PATH:OPENFPGA_PATH}/openfpga_flow/tech/PTM_45nm/45nm.xml
   power_analysis = true
   spice_output=false
   verilog_output=true
   timeout_each_job = 20*60
   fpga_flow=vpr_blif

   [OpenFPGA_SHELL]
   openfpga_shell_template=${PATH:OPENFPGA_PATH}/openfpga_flow/openfpga_shell_scripts/example_script.openfpga
   openfpga_arch_file=${PATH:OPENFPGA_PATH}/openfpga_flow/openfpga_arch/k6_frac_N10_adder_register_scan_chain_depop50_spypad_40nm_openfpga.xml
   openfpga_sim_setting_file=${PATH:OPENFPGA_PATH}/openfpga_flow/openfpga_simulation_settings/auto_sim_openfpga.xml

   [ARCHITECTURES]
   arch0=${PATH:OPENFPGA_PATH}/openfpga_flow/vpr_arch/k6_frac_N10_tileable_adder_register_scan_chain_depop50_spypad_40nm.xml

   [BENCHMARKS]
   bench0=${PATH:OPENFPGA_PATH}/openfpga_flow/benchmarks/micro_benchmark/and2/and2.blif
   # Cannot pass automatically. Need change in .v file to match ports
   # When passed, we can replace the and2 benchmark
   #bench0=${PATH:OPENFPGA_PATH}/openfpga_flow/benchmarks/micro_benchmark/test_mode_low/test_mode_low.blif

   [SYNTHESIS_PARAM]
   bench0_top = and2
   bench0_act = ${PATH:OPENFPGA_PATH}/openfpga_flow/benchmarks/micro_benchmark/and2/and2.act
   bench0_verilog = ${PATH:OPENFPGA_PATH}/openfpga_flow/benchmarks/micro_benchmark/and2/and2.v

   #bench0_top = test_mode_low
   #bench0_act = ${PATH:OPENFPGA_PATH}/openfpga_flow/benchmarks/micro_benchmark/test_mode_low/test_mode_low.act
   #bench0_verilog = ${PATH:OPENFPGA_PATH}/openfpga_flow/benchmarks/micro_benchmark/test_mode_low/test_mode_low.v
   bench0_chan_width = 300

   [SCRIPT_PARAM_MIN_ROUTE_CHAN_WIDTH]
   end_flow_with_test=
   #vpr_fpga_verilog_formal_verification_top_netlist=

Our OpenFPGA task will now run the full testbench. We run the task with the following command from the root directory of OpenFPGA:

.. code-block:: bash

   python3 openfpga_flow/scripts/run_fpga_task.py fpga_verilog/spypad --debug --show_thread_logs

.. note:: Python 3.8 or later is required to run this task

We can now see the instantiation of these spypads in ``fpga_top.v`` and ``luts.v``. We will start by viewing ``luts.v`` with the following command:

.. code-block:: bash

   emacs openfpga_flow/tasks/fpga_verilog/spypad/latest/k6_frac_N10_tileable_adder_register_scan_chain_depop50_spypad_40nm/and2/MIN_ROUTE_CHAN_WIDTH/SRC/sub_module/luts.verilog

The spypads are coming from the ``frac_lut6_spypad`` circuit model. In ``luts.v``, the ``frac_lut6_spypad`` module is defined around **LINE150** and looks as follows:

.. code-block:: verilog

   module frac_lut6_spypad(in,
   sram,
   sram_inv,
   mode,
   mode_inv,
   lut4_out,
   lut5_out,
   lut6_out);
   //----- INPUT PORTS -----
   input [0:5] in;
   //----- INPUT PORTS -----
   input [0:63] sram;
   //----- INPUT PORTS -----
   input [0:63] sram_inv;
   //----- INPUT PORTS -----
   input [0:1] mode;
   //----- INPUT PORTS -----
   input [0:1] mode_inv;
   //----- OUTPUT PORTS -----
   output [0:3] lut4_out;
   //----- OUTPUT PORTS -----
   output [0:1] lut5_out;
   //----- OUTPUT PORTS -----
   output [0:0] lut6_out;

The ``fpga_top.v`` file has some similarities. We can view the ``fpga_top.v`` file by running the following command:

.. code-block:: bash

   emacs openfpga_flow/tasks/fpga_verilog/spypad/latest/k6_frac_N10_tileable_adder_register_scan_chain_depop50_spypad_40nm/and2/MIN_ROUTE_CHAN_WIDTH/SRC/fpga_top.v

If we look at the module definition and ports of ``fpga_top.v`` we should see the following:

.. code-block:: verilog

   module fpga_top(pReset,
                prog_clk,
                TESTEN,
                set,
                reset,
                clk,
                gfpga_pad_frac_lut6_spypad_lut4_out,
                gfpga_pad_frac_lut6_spypad_lut5_out,
                gfpga_pad_frac_lut6_spypad_lut6_out,
                gfpga_pad_GPIO_PAD,
                ccff_head,
                ccff_tail);
   //----- GLOBAL PORTS -----
   input [0:0] pReset;
   //----- GLOBAL PORTS -----
   input [0:0] prog_clk;
   //----- GLOBAL PORTS -----
   input [0:0] TESTEN;
   //----- GLOBAL PORTS -----
   input [0:0] set;
   //----- GLOBAL PORTS -----
   input [0:0] reset;
   //----- GLOBAL PORTS -----
   input [0:0] clk;
   //----- GPOUT PORTS -----
   output [0:3] gfpga_pad_frac_lut6_spypad_lut4_out;
   //----- GPOUT PORTS -----
   output [0:1] gfpga_pad_frac_lut6_spypad_lut5_out;
   //----- GPOUT PORTS -----
   output [0:0] gfpga_pad_frac_lut6_spypad_lut6_out;
   //----- GPIO PORTS -----
   inout [0:7] gfpga_pad_GPIO_PAD;
   //----- INPUT PORTS -----
   input [0:0] ccff_head;
   //----- OUTPUT PORTS -----
   output [0:0] ccff_tail;

Using :ref:`fig_gpout_ports` as a guide, we can relate our task like :numref:`fig_gpout_example`

.. _fig_gpout_example:

.. figure:: ./figures/lut6_Example_Spypad.svg
   :scale: 100%

   An illustrative example of the ``lut6`` spypad sourced from inside a logic element.

   
We can view testbench waveforms with GTKWave by running the following command from the root directory:

.. code-block:: bash

   gtkwave openfpga_flow/tasks/fpga_verilog/spypad/latest/k6_frac_N10_tileable_adder_register_scan_chain_depop50_spypad_40nm/and2/MIN_ROUTE_CHAN_WIDTH/and2_formal.vcd &

.. note:: Information on GTKWave can be found on our documentation page located here: :ref:`from_verilog_to_verification`

The waveforms will appear similar to :numref:`fig_spypad_waves`

.. _fig_spypad_waves:

.. figure:: ./figures/spypad_waveforms.png
   :width: 100%

   Waveforms of ``frac_lut6`` spypads

Building Spypads
~~~~~~~~~~~~~~~~

We will modify the `k6_frac_N10_adder_chain_40nm_openfpga.xml <https://github.com/lnis-uofu/OpenFPGA/blob/tutorials/openfpga_flow/openfpga_arch/k6_frac_N10_adder_chain_40nm_openfpga.xml>`_ file found in OpenFPGA to expose the **sumout** output from the **ADDF** module. We can start modifying
the file by running the following command:

.. code-block:: bash

   emacs openfpga_flow/openfpga_arch/k6_frac_N10_adder_chain_40nm_openfpga.xml

Replace **LINE214** with the following:

.. code-block:: xml

   <port type="output" prefix="sumout" lib_name="SUM" size="1" is_global=”true” is_io=”true”/>

**sumout** is now a global output. **sumout** will show up in the ``fpga_top.v`` file and will have waveforms in GTKWave if we run the **full testbench**. To run the 
**full testbench**, we have to modify the ``hard_adder`` configuration file:

.. code-block:: bash

   emacs openfpga_flow/tasks/fpga_verilog/adder/hard_adder/config/task.conf

Comment out the last line of the file to run the **full testbench**:

.. code-block:: python

   #vpr_fpga_verilog_formal_verification_top_netlist=

We now run the task to see our changes:

.. code-block:: bash

   python3 openfpga_flow/scripts/run_fpga_task.py fpga_verilog/adder/hard_adder --debug --show_thread_logs

We can view the global ports in ``fpga_top.v`` by running the following command:

.. code-block:: bash

   emacs openfpga_flow/tasks/fpga_verilog/adder/hard_adder/run064/k6_frac_N10_tileable_adder_chain_40nm/and2/MIN_ROUTE_CHAN_WIDTH/SRC/fpga_top.v

The ``fpga_top.v`` should have the following in its module definition:

.. code-block:: verilog

   module fpga_top(pReset,
                prog_clk,
                set,
                reset,
                clk,
                gfpga_pad_ADDF_sumout,
                gfpga_pad_GPIO_PAD,
                ccff_head,
                ccff_tail);
   //----- GLOBAL PORTS -----
   input [0:0] pReset;
   //----- GLOBAL PORTS -----
   input [0:0] prog_clk;
   //----- GLOBAL PORTS -----
   input [0:0] set;
   //----- GLOBAL PORTS -----
   input [0:0] reset;
   //----- GLOBAL PORTS -----
   input [0:0] clk;
   //----- GPOUT PORTS -----
   output [0:19] gfpga_pad_ADDF_sumout;
   
The architecture will now look like :numref:`fig_addf_example`

.. _fig_addf_example:

.. figure:: ./figures/ADDF_Example_Spypad.svg
   :scale: 100%
   
   An illustrative example of the sumout spypad sourced from an adder inside a logic element. There are 10 logic elements in a CLB, and we are looking at the 1st logic element.

We can view the waveform by running GTKWave:

.. code-block:: bash

   gtkwave openfpga_flow/tasks/fpga_verilog/adder/hard_adder/latest/k6_frac_N10_tileable_adder_chain_40nm/and2/MIN_ROUTE_CHAN_WIDTH/and2_formal.vcd &

The waveform should have some changes to its value. An example of what it may look like is displayed in :numref:`fig_spy_adder`

.. _fig_spy_adder:

.. figure:: ./figures/spyadder_waveform.png
   :width: 100%

   Waveforms of ``sumout`` spypad

Conclusion
~~~~~~~~~~

In this tutorial, we have shown how to build spypads into OpenFPGA Architectures using XML Syntax. If you have any issues, feel free to :ref:`contact` us.