add openfpga shell documentation

docs/source/index.rst

@@ -27,6 +27,8 @@ Welcome to OpenFPGA's documentation!
    :maxdepth: 2
    :caption: OpenFPGA Tools
 
+   openfpga_shell/index
+
    fpga_spice/index
 
    fpga_verilog/index

docs/source/openfpga_shell/index.rst

@@ -0,0 +1,14 @@
+OpenFPGA Interface
+------------------
+
+.. _openfpga_shell:
+   OpenFPGA Shell
+ 
+.. toctree::
+   :maxdepth: 2
+
+   launch_openfpga_shell
+
+   openfpga_script
+  
+   openfpga_commands

docs/source/openfpga_shell/launch_openfpga_shell.rst

@@ -0,0 +1,21 @@
+.. _launch_openfpga_shell:
+
+Launch OpenFPGA Shell
+---------------------
+
+OpenFPGA employs a shell-like user interface, in order to integrate all the tools in a well-modularized way.
+Currently, OpenFPGA shell is an unified platform to call ``vpr``, ``FPGA-Verilog``, ``FPGA-Bitstream``, ``FPGA-SDC`` and ``FPGA-SPICE``.
+To launch OpenFPGA shell, users can choose two modes.
+
+.. option::	--interactive or -i
+
+  Launch OpenFPGA in interactive mode where users type-in command by command and get runtime results
+
+.. option::	--file or -f
+
+  Launch OpenFPGA in script mode where users write commands in scripts and FPGA will execute them
+
+.. option::	--help or -h
+	
+  Show the help desk
+

docs/source/openfpga_shell/openfpga_commands.rst

@@ -0,0 +1,184 @@
+.. _openfpga_commands:
+
+Commands
+--------
+
+As OpenFPGA integrates various tools, the commands are categorized into different classes:
+
+Basic Commands
+~~~~~~~~~~~~~~
+
+.. option:: help
+
+  Show help desk to list all the available commands
+
+.. option:: exit
+
+  Exit OpenFPGA shell
+
+VPR
+~~~
+
+.. option:: vpr
+  
+  OpenFPGA allows users to call ``vpr`` in the standard way as documented in vtr project.
+
+Setup OpenFPGA
+~~~~~~~~~~~~~~
+
+.. option:: read_openfpga_arch
+
+  Read the XML architecture file required by OpenFPGA
+
+  - ``--file`` or ``-f`` Specify the file name 
+
+  - ``--verbose`` Show verbose log
+
+.. option:: write_openfpga_arch
+
+  Write the OpenFPGA XML architecture file to a file
+
+  - ``--file`` or ``-f`` Specify the file name 
+
+  - ``--verbose`` Show verbose log
+
+.. option:: link_openfpga_arch
+
+  Annotate the OpenFPGA architecture to VPR data base
+
+  - ``--activity_file`` Specify the signal activity file
+
+  - ``--sort_gsb_chan_node_in_edges`` Sort the edges for the routing tracks in General Switch Blocks (GSBs). Strongly recommand to turn this on for uniquifying the routing modules
+
+  - ``--verbose`` Show verbose log
+
+.. option:: check_netlist_naming_conflict 
+
+  Check and correct any naming conflicts in the BLIF netlist
+  This is strongly recommended. Otherwise, the outputted Verilog netlists may not be compiled successfully.
+
+  .. note:: This command may be deprecated in future when merged to VPR upstream
+  
+  - ``--fix`` Apply fix-up to the names that violate the syntax
+
+  - ``--report <.xml>`` Report the naming fix-up to a log file
+
+.. option:: pb_pin_fixup
+
+  Apply fix-up to clustering nets based on routing results
+  This is strongly recommended. Otherwise, the bitstream generation may be wrong
+
+  .. note:: This command may be deprecated in future when merged to VPR upstream
+  
+  - ``--verbose`` Show verbose log
+   
+.. option:: lut_truth_table_fixup
+
+  Apply fix-up to Look-Up Table truth tables based on packing results
+
+  .. note:: This command may be deprecated in future when merged to VPR upstream
+
+  - ``--verbose`` Show verbose log
+  
+.. option:: build_fabric
+
+  Build the module graph. This is a must-run command before launching FPGA-Verilog, FPGA-Bitstream, FPGA-SDC and FPGA-SPICE
+
+  - ``--compress_routing`` Enable compression on routing architecture modules. Strongly recommend this as it will minimize the number of routing modules to be outputted. It can reduce the netlist size significantly.
+  
+  - ``--duplicate_grid_pin`` Enable pin duplication on grid modules. This is optional unless ultra-dense layout generation is needed
+
+  - ``--verbose`` Show verbose log
+  
+FPGA-Bitstream
+~~~~~~~~~~~~~~
+
+.. option:: repack
+
+  Repack the netlist to physical pbs
+  This must be done before bitstream generator and testbench generation
+  Strongly recommend it is done after all the fix-up have been applied
+   
+  - ``--verbose`` Show verbose log
+
+.. option:: build_architecture_bitstream
+
+  Decode VPR implementing results to an fabric-independent bitstream database 
+  
+  - ``--file`` or ``-f`` Output the fabric-independent bitstream to an XML file
+  
+  - ``--verbose`` Show verbose log
+
+.. option:: build_fabric_bitstream
+
+  Reorganize the bitstream database for a specific FPGA fabric
+
+  - ``--verbose`` Show verbose log
+  
+FPGA-Verilog
+~~~~~~~~~~~~
+
+.. option:: write_fabric_verilog
+
+  Write the Verilog netlist for FPGA fabric based on module graph
+
+  - ``--file`` or ``-f`` Specify the output directory for the Verilog netlists
+
+  - ``--explict_port_mapping`` Use explict port mapping when writing the Verilog netlists
+
+  - ``--include_timing`` Output timing information to Verilog netlists for primitive modules
+ 
+  - ``--include_signal_init`` Output signal initialization to Verilog netlists for primitive modules
+
+  - ``--support_icarus_simulator`` Output Verilog netlists with syntax that iVerilog simulatorcan accept
+
+  - ``--print_user_defined_template`` Output a template Verilog netlist for all the user-defined ``circuit models`` in :ref:`circuit_library`. This aims to help engineers to check what is the port sequence required by top-level Verilog netlists
+
+  - ``--verbose`` Show verbose log
+
+.. option:: write_verilog_testbench
+ 
+  Write the Verilog testbench for FPGA fabric
+
+  - ``--file`` or ``-f`` The output directory for all the testbench netlists. We suggest the use of same output directory as fabric Verilog netlists
+
+  - ``--reference_benchmark_file_path`` Must specify the reference benchmark Verilog file if you want to output any testbenches
+
+  - ``--print_top_testbench`` Enable top-level testbench which is a full verification including programming circuit and core logic of FPGA
+
+  - ``--print_formal_verification_top_netlist`` Generate a top-level module which can be used in formal verification
+
+  - ``--print_preconfig_top_testbench`` Enable pre-configured top-level testbench which is a fast verification skipping programming phase
+
+  - ``--print_simulation_ini`` Output an exchangeable simulation ini file, which is needed only when you need to interface different HDL simulators using openfpga flow-run scripts
+
+FPGA-SDC
+~~~~~~~~
+
+.. option:: write_pnr_sdc
+ 
+  Write the SDC files for PnR backend
+  
+  - ``--file`` or ``-f`` Specify the output directory for SDC files
+
+  - ``--constrain_global_port`` Constrain all the global ports of FPGA fabric
+
+  - ``--constrain_grid`` Constrain all the grids of FPGA fabric
+
+  - `--constrain_sb`` Constrain all the switch blocks of FPGA fabric
+
+  - ``--constrain_cb`` Constrain all the connection blocks of FPGA fabric
+
+  - ``--constrain_configurable_memory_outputs`` Constrain all the outputs of configurable memories of FPGA fabric
+
+  - ``--constrain_routing_multiplexer_outputs`` Constrain all the outputs of routing multiplexer of FPGA fabric
+
+  - ``--constrain_switch_block_outputs`` Constrain all the outputs of switch blocks of FPGA fabric
+  
+  - ``--verbose`` Enable verbose output
+
+.. option:: write_analysis_sdc
+
+  Write the SDC to run timing analysis for a mapped FPGA fabric
+
+  - ``--file`` or ``-f`` Specify the output directory for SDC files

docs/source/openfpga_shell/openfpga_script.rst

@@ -0,0 +1,72 @@
+.. _openfpga_script_format:
+
+OpenFPGA Script Format
+----------------------
+
+OpenFPGA accepts a simplified tcl-like script format.
+Commented lines are started with `#`.
+Note that comments can be added inline or as a new line.
+
+The following is an example.
+
+.. code-block:: python
+
+  # Run VPR for the s298 design
+  vpr ./test_vpr_arch/k6_frac_N10_40nm.xml ./test_blif/and.blif --clock_modeling route #--write_rr_graph example_rr_graph.xml
+  
+  # Read OpenFPGA architecture definition
+  read_openfpga_arch -f ./test_openfpga_arch/k6_frac_N10_40nm_openfpga.xml
+  
+  # Write out the architecture XML as a proof
+  #write_openfpga_arch -f ./arch_echo.xml
+  
+  # Annotate the OpenFPGA architecture to VPR data base
+  link_openfpga_arch --activity_file ./test_blif/and.act --sort_gsb_chan_node_in_edges #--verbose
+  
+  # Check and correct any naming conflicts in the BLIF netlist
+  check_netlist_naming_conflict --fix --report ./netlist_renaming.xml
+  
+  # Apply fix-up to clustering nets based on routing results
+  pb_pin_fixup --verbose
+  
+  # Apply fix-up to Look-Up Table truth tables based on packing results
+  lut_truth_table_fixup #--verbose
+  
+  # Build the module graph 
+  #  - Enabled compression on routing architecture modules
+  #  - Enable pin duplication on grid modules 
+  build_fabric --compress_routing --duplicate_grid_pin #--verbose
+  
+  # Repack the netlist to physical pbs
+  # This must be done before bitstream generator and testbench generation
+  # Strongly recommend it is done after all the fix-up have been applied
+  repack #--verbose
+  
+  # Build the bitstream 
+  #  - Output the fabric-independent bitstream to a file
+  build_architecture_bitstream --verbose --file /var/tmp/xtang/openfpga_test_src/fabric_indepenent_bitstream.xml
+  
+  # Build fabric-dependent bitstream
+  build_fabric_bitstream --verbose
+  
+  # Write the Verilog netlist for FPGA fabric
+  #  - Enable the use of explicit port mapping in Verilog netlist
+  write_fabric_verilog --file /var/tmp/xtang/openfpga_test_src/SRC --explicit_port_mapping --include_timing --include_signal_init --support_icarus_simulator --print_user_defined_template --verbose
+  
+  # Write the Verilog testbench for FPGA fabric
+  #  - We suggest the use of same output directory as fabric Verilog netlists
+  #  - Must specify the reference benchmark file if you want to output any testbenches
+  #  - Enable top-level testbench which is a full verification including programming circuit and core logic of FPGA
+  #  - Enable pre-configured top-level testbench which is a fast verification skipping programming phase
+  #  - Simulation ini file is optional and is needed only when you need to interface different HDL simulators using openfpga flow-run scripts
+  write_verilog_testbench --file /var/tmp/xtang/openfpga_test_src/SRC --reference_benchmark_file_path /var/tmp/xtang/and.v --print_top_testbench --print_preconfig_top_testbench --print_simulation_ini /var/tmp/xtang/openfpga_test_src/simulation_deck.ini
+  
+  # Write the SDC files for PnR backend
+  #  - Turn on every options here 
+  write_pnr_sdc --file /var/tmp/xtang/openfpga_test_src/SDC 
+  
+  # Write the SDC to run timing analysis for a mapped FPGA fabric
+  write_analysis_sdc --file /var/tmp/xtang/openfpga_test_src/SDC_analysis
+  
+  # Finish and exit OpenFPGA
+  exit