From 9f743f7f4ed3d42fae3b1c7128b9a6415280d5bb Mon Sep 17 00:00:00 2001 From: Xifan Tang Date: Tue, 10 Mar 2020 20:54:42 -0600 Subject: [PATCH] add openfpga shell documentation --- docs/source/index.rst | 2 + docs/source/openfpga_shell/index.rst | 14 ++ .../openfpga_shell/launch_openfpga_shell.rst | 21 ++ .../openfpga_shell/openfpga_commands.rst | 184 ++++++++++++++++++ .../source/openfpga_shell/openfpga_script.rst | 72 +++++++ 5 files changed, 293 insertions(+) create mode 100644 docs/source/openfpga_shell/index.rst create mode 100644 docs/source/openfpga_shell/launch_openfpga_shell.rst create mode 100644 docs/source/openfpga_shell/openfpga_commands.rst create mode 100644 docs/source/openfpga_shell/openfpga_script.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 34beae468..d3452b771 100644 --- a/docs/source/index.rst +++ b/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 diff --git a/docs/source/openfpga_shell/index.rst b/docs/source/openfpga_shell/index.rst new file mode 100644 index 000000000..0aa515e23 --- /dev/null +++ b/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 diff --git a/docs/source/openfpga_shell/launch_openfpga_shell.rst b/docs/source/openfpga_shell/launch_openfpga_shell.rst new file mode 100644 index 000000000..3ef6e9fb5 --- /dev/null +++ b/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 + diff --git a/docs/source/openfpga_shell/openfpga_commands.rst b/docs/source/openfpga_shell/openfpga_commands.rst new file mode 100644 index 000000000..79c95d248 --- /dev/null +++ b/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 diff --git a/docs/source/openfpga_shell/openfpga_script.rst b/docs/source/openfpga_shell/openfpga_script.rst new file mode 100644 index 000000000..dde33a044 --- /dev/null +++ b/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