From 06c0dbb3288f8091c8dc26b13949383381c778f2 Mon Sep 17 00:00:00 2001 From: Ganesh Gore Date: Sat, 31 Aug 2019 15:19:34 -0600 Subject: [PATCH] Added docuementation for fpga_flow --- docs/Makefile | 9 +- docs/source/run_fpga_flow.rst | 181 +++++++++++++++++++++++++ openfpga_flow/scripts/run_fpga_flow.py | 18 ++- 3 files changed, 199 insertions(+), 9 deletions(-) create mode 100755 docs/source/run_fpga_flow.rst diff --git a/docs/Makefile b/docs/Makefile index 9d20886ea..1f299ec6b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -7,7 +7,7 @@ SPHINXBUILD = sphinx-build SOURCEDIR = source BUILDDIR = build -PAPER = +PAPER = PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter ALL_SPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR) @@ -16,7 +16,10 @@ ALL_SPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SO help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -clean: +livehtml: + sphinx-autobuild -b html $(ALL_SPHINXOPTS) $(BUILDDIR)/html + +clean: rm -rf $(BUILDDIR)/* .PHONY: help clean Makefile @@ -27,4 +30,4 @@ clean: @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) #html: # $(SPHINXBUILD) -b html $@ "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) - + diff --git a/docs/source/run_fpga_flow.rst b/docs/source/run_fpga_flow.rst new file mode 100755 index 000000000..7f22dbfec --- /dev/null +++ b/docs/source/run_fpga_flow.rst @@ -0,0 +1,181 @@ +.. _run_fpga_flow: + +run_fpga_flow +--------------- + +This python script executes the supported openfpga flow for a +single benchmark and architecture file for given script parameters. + +The script is located at:: + + ${OPENFPGA_PATH}/openfpga_flow/scripts/run_fpga_flow.py + +.. program:: run_fpga_flow.py + +Basic Usage +~~~~~~~~~~~ + +At a minimum ``open_fpga_flow.py`` requires following command-line arguments:: + + open_fpga_flow.py --top_module + +where: + + * ```` is the target :ref:`FPGA architecture ` + * ```` The list of files in the benchmark (Supports ../directory/\*.v) + * ```` The name of the top level module in Verilog project + +.. note:: + The script will create a ``tmp`` run directory in base OpenFPGA path, unless otherwise specified with the :option:`--run_dir` option. + All stages of the flow will be run within run directory. + Several intermediate files will be generated and maintian in run directory. + The path variables declared in architecture XML file will be resolved with absolute path and copied to the ``tmp/arch`` directory before executing flow. + All the benchmark files provided will be copied to ``tmp/bench`` directory without maintaining any directory structure. + **Users should ensure that no important files are kept in this directory as script will clear directory before each execution** + +OpenFPGA Variables +~~~~~~~~~~~~~~~~~~ +Frequently, while running OpenFPGA flow User is suppose to refer external files. +To avoid long names and referencing errors user can use +following openfpga variables. +These variables are resolved with absolute path while execution making +each run independent of launch directory. + + + * ```` Path to the base OpenFPGA directory + * ```` Path to the run_fpga_flow script directory + * ```` Path where spice netlists are saved + * ```` Path where verilog modules are saved + * ```` Path where all characterized XML files are stored + +For example in architecture file path vairable can be used as follows:: + + .... lib_path="${TECH_PATH}/PTM_45nm/45nm.pm" .... + +Output +~~~~~~ +Based on which flow is executed, resulting intermediate files are generated in run_directory + +The output log of the script provides status of each stage to the user. +If any stage failed to execute, the output log will indicate the stage at which execution failed, and execution traceback. + +In case of successful execution, The openfpga flow script will parse +parameters lited in configuration from different result files and will create +``vpr_stat.txt``, ``vpr_stat_power.txt`` \(optional\) file in run_directory. + +Advanced Usage +~~~~~~~~~~~~~~ + +User can pass additional *optional* command arguments to ``run_fpga_flow.py`` script:: + + run_fpga_flow.py [] [] [] [] [] [] + + +where: + + * ```` are additional arguments passed to ``run_fpga_flow.py`` (described below), + * ```` Any argument prefixed with ``--vpr-*`` will be forwarded to vpr script as it is. The detail of supported vpr argument is available ``Add corrrect reference`` + * ```` are any arguments not recognized by ``run_vtr_flow.pl``. These will be forwarded to VPR. + * ```` these arguments will be passed to ACE activity estimator program + +For example:: + + run_fpga_flow.py my_circuit.v my_arch.xml -track_memory_usage --pack --place + +will run the VTR flow to map the circuit ``my_circuit.v`` onto the architecture ``my_arch.xml``; the arguments ``--pack`` and ``--place`` will be passed to VPR (since they are unrecognized arguments to ``run_vtr_flow.pl``). +They will cause VPR to perform only :ref:`packing and placement `. + +Detailed Command-line Options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + .. Note:: All the commnadline arguments starting with ``vpr_*`` , ``fpga-verilog_*`` , ``fpga-spice_*`` or ``fpga-bitstream_*`` will be passed to VPR without suffix + +General Arguments +^^^^^^^^^^^^^^^^^ + +.. option:: --top_module + + Provide top module name of the benchmark. Default ``top`` + +.. option:: --run_dir + + Using this option user can provide custom path as a run directory. Default is ``tmp`` directory in OpenFPGA root path. + +.. option:: --K + + This option defines the number of inputs to the LUT. By default script parses provided architecture file and finds out inputs to the biggest LUT. + +.. option:: --yosys_tmpl + + This option allows user to provide a custom yosys template + while running a yosys_vpr flow. Default template is stored in a directory ``open_fpga_flow\misc\ys_tmpl_yosys_vpr_flow.ys``. Yosys template script supports ``TOP_MODULE`` ``READ_VERILOG_FILE`` ``LUT_SIZE`` & ``OUTPUT_BLIF`` variables, which can be used as ``${var_name}``. Alternately, user can create a copy and modify according to their need. + +.. option:: --debug + + To enable detail logs printing + +.. option:: --flow_config + + User can provide option flow ocnfiguration file to override some of the default script paramteres. + for detail information refer :ref:`OpenFPGA Flow Configuration ` + +ACE Arguments +^^^^^^^^^^^^^ +.. option:: --black_box_ace + + Performs ACE simulation on black box [deprecated] + +VPR RUN Arguments +^^^^^^^^^^^^^^^^^ + +.. option:: --fix_route_chan_width + + Perfoms VPR implementation for fixed number of channels defined as the 'channel_number' + +.. option:: --min_route_chan_width + + Performs VPR implementation to get minimum channel width and then perform fixed channel rerouting with ``percentage_slack`` increase in the channle width. + +.. option:: --max_route_width_retry + + Number of times the channel width should be incresese and attempt VPR implmenetation, while performaning ``min_route_chan_width`` + +.. option:: --power +.. option:: --power_tech + + +blif_vpr_flow Arguments +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. option:: --activity_file + + Activity to be used for the given benchmark while running ``blif_vpr_flow`` + +.. option:: --base_verilog + + Verilog benchmark file to perform verification while running ``bliff_vpr_flow`` + + + +.. _OpenFPGA_Conf_File: +OpenFPGA Flow Configuration file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The OpenFPGA Flow configuration file consists of following sections + + * ``CAD_TOOLS_PATH`` + Lists executable file path for different CAD tools used in the script + + * ``FLOW_SCRIPT_CONFIG`` + Lists the supported flows by the script. + + * ``DEFAULT_PARSE_RESULT_VPR`` + Default prarameters to parse from Place, Pack and Route output. + + * ``DEFAULT_PARSE_RESULT_POWER`` + Default prarameters to parse from VPR power analysis output. + + * ``INTERMIDIATE_FILE_PREFIX`` + [Not implemented yet] + +Default OpenFPGA_flow Configuration file is located in ``open_fpga_flow\misc\fpgaflow_default_tool_path.conf``. +User supplied configuration file overrides or extendes the dafult configuration. \ No newline at end of file diff --git a/openfpga_flow/scripts/run_fpga_flow.py b/openfpga_flow/scripts/run_fpga_flow.py index 3a35830bd..946954329 100644 --- a/openfpga_flow/scripts/run_fpga_flow.py +++ b/openfpga_flow/scripts/run_fpga_flow.py @@ -43,9 +43,15 @@ openfpga_base_dir = os.path.abspath( launch_dir = os.getcwd() # Path section to append in configuration file to interpolate path -script_env_vars = {"PATH": { - "OPENFPGA_FLOW_PATH": flow_script_dir, - "OPENFPGA_PATH": openfpga_base_dir}} +script_env_vars = ({"PATH": { + "OPENFPGA_FLOW_PATH": task_script_dir, + "ARCH_PATH": os.path.join("${PATH:OPENFPGA_PATH}", "arch"), + "BENCH_PATH": os.path.join("${PATH:OPENFPGA_PATH}", "benchmarks"), + "TECH_PATH": os.path.join("${PATH:OPENFPGA_PATH}", "tech"), + "SPICENETLIST_PATH": os.path.join("${PATH:OPENFPGA_PATH}", "SpiceNetlists"), + "VERILOG_PATH": os.path.join("${PATH:OPENFPGA_PATH}", "VerilogNetlists"), + "OPENFPGA_PATH": os.path.abspath(os.path.join(task_script_dir, os.pardir, + os.pardir))}}) # = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = # Reading command-line argument @@ -66,7 +72,7 @@ parser.add_argument('benchmark_files', type=str, nargs='+') # Optional arguments parser.add_argument('--top_module', type=str, default="top") parser.add_argument('--fpga_flow', type=str, default="yosys_vpr") -parser.add_argument('--cad_tool_conf', type=str, +parser.add_argument('--flow_config', type=str, help="CAD tools path overrides default setting") parser.add_argument('--run_dir', type=str, default=os.path.join(openfpga_base_dir, 'tmp'), @@ -281,8 +287,8 @@ def read_script_config(): default_cad_tool_conf = os.path.join(flow_script_dir, os.pardir, 'misc', 'fpgaflow_default_tool_path.conf') config.read_file(open(default_cad_tool_conf)) - if args.cad_tool_conf: - config.read_file(open(args.cad_tool_conf)) + if args.flow_config: + config.read_file(open(args.flow_config)) if not "CAD_TOOLS_PATH" in config.sections(): clean_up_and_exit("Missing CAD_TOOLS_PATH in openfpga_flow config") cad_tools = config["CAD_TOOLS_PATH"]