From 241b001282d62313aa59dbb1b3fc019ec9c5fd87 Mon Sep 17 00:00:00 2001 From: Ganesh Gore Date: Sun, 1 Sep 2019 22:15:53 -0600 Subject: [PATCH] Added openfpga_task doc --- docs/source/index.rst | 11 +- docs/source/run_fpga_flow.rst | 6 +- docs/source/run_fpga_task.rst | 213 +++++++++++++++++++++++++ openfpga_flow/scripts/run_fpga_task.py | 1 + 4 files changed, 226 insertions(+), 5 deletions(-) create mode 100644 docs/source/run_fpga_task.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 1c5132355..51fd1b119 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,10 +12,15 @@ Welcome to OpenFPGA's documentation! motivation .. toctree:: - :caption: Getting Started + :caption: Getting Started eda_flow + run_fpga_flow + + run_fpga_task + + .. toctree:: :maxdepth: 2 :caption: Tools Guide @@ -37,10 +42,10 @@ Welcome to OpenFPGA's documentation! .. toctree:: :maxdepth: 2 :caption: Appendix - + contact reference - + For more information on the VTR see vtr_doc_ or vtr_github_ For more information on the Yosys see yosys_doc_ or yosys_github_ diff --git a/docs/source/run_fpga_flow.rst b/docs/source/run_fpga_flow.rst index 051b5064a..3a182f6d7 100755 --- a/docs/source/run_fpga_flow.rst +++ b/docs/source/run_fpga_flow.rst @@ -1,6 +1,6 @@ .. _run_fpga_flow: -run_fpga_flow +OpenFPGA Flow --------------- This python script executes the supported OpenFPGA flow for a @@ -33,6 +33,8 @@ where: 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: + OpenFPGA Variables ~~~~~~~~~~~~~~~~~~ Frequently, while running OpenFPGA flow User is suppose to refer external files. @@ -178,4 +180,4 @@ The OpenFPGA Flow configuration file consists of following sections [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 extends the default configuration. \ No newline at end of file +User-supplied configuration file overrides or extends the default configuration. diff --git a/docs/source/run_fpga_task.rst b/docs/source/run_fpga_task.rst new file mode 100644 index 000000000..c25527546 --- /dev/null +++ b/docs/source/run_fpga_task.rst @@ -0,0 +1,213 @@ +.. _run_fpga_task: + +OpenFPGA Task +--------------- + +Tasks provide a framework for running the :ref:`run_fpga_flow` on +multiple benchmarks, architectures and set of OpenFPGA parameters. +The structure of the framework is very similar to +`VTR-Tasks `_ +implementation with additional functionality and minor file extention changes. + +Task Directory +~~~~~~~~~~~~~~ + +The tasks are store in a ``TASK_DIRECTORY``, which by default points to +``${OPENFPGA_PATH}/openfpga_flow/tasks``. Every directory or sub-directory in +task directory consisting of ``../config/task.conf`` file can be reffered as a +task. + +To create as task name called ``basic_flow`` following directory has to exist:: + + ${TASK_DIRECTORY}/basic_flow/conf/task.conf + +Similarly ``regression/regression_quick`` expect following structure:: + + ${TASK_DIRECTORY}/regression/regression_quick/conf/task.conf + + +Running OpenFPGA Task: +~~~~~~~~~~~~~~~~~~~~~~ + +At a minimum ``open_fpga_flow.py`` requires following command-line arguments:: + + open_fpga_flow.py ... + +where: + + * ```` is the name of the task to run + + +Craeating A New OpenFPGA Task: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Create the folder ``${TASK_DIRECTORY}/`` and create a file called +``${TASK_DIRECTORY}//config/task.conf`` in it. + + + +Configuring a New Task +~~~~~~~~~~~~~~~~~~~~~~ + +The task configuration file ``task.conf`` consists of ``GENERAL``, +``ARCHITECTURES``, ``BENCHMARKS``, ``SYNTHESIS_PARAM`` and +``SCRIPT_PARAM_`` sections. +Declaring all the above sections are mandatory. + +.. note:: + Configuration file supports all the OpenFPGA Variables refer + :ref:`openfpga-variables` section to know more. Variables in configuration + file is declares as ``${PATH:}`` + +General Section +^^^^^^^^^^^^^^^ + +.. option:: fpga_flow== + + Defines which OpenFPGA flow to run. By default ``yosys_vpr`` is executed. + +.. option:: power_analysis= + + Specifies whether to perform power analysis or not. + +.. option:: power_tech_file= + + Declares which tech XML file to be used while perforing Power Analysis. + +.. option:: spice_output= + + Setting up this variable generates Spice Netlist at the end of the flow. + Equivalent of passing ``--vpr_fpga_spice`` command to :ref:`run_fpga_flow` + +.. option:: verilog_output= + + Setting up this variable generates Verilog Netlist at the end of the flow. + Equivalent of passing ``--vpr_fpga_spice`` command to :ref:`run_fpga_flow` + +.. option:: timeout_each_job= + + Specifies the the timeout for each :ref:`run_fpga_flow` execution. Default + is set to ``20 min`` + + +Architectures Sections +^^^^^^^^^^^^^^^^^^^^^^ + + User can define the list of architecure files in this section. + +.. option:: arch= + + The ``arch_label`` variable can be any number of string without + white-spaces. ``xml_architecture_file_path`` is path to the actual XML + architecture file + +.. note:: + + In final OpenFPGA Task result the architecture will be referred by its + ``arch_label``. + +Benchmarks Sections +^^^^^^^^^^^^^^^^^^^ + + User can define the list of benchmarks files in this section. + +.. option:: bench= + + The ``bench_label`` variable can be any number of string without + white-spaces. ``xml_architecture_file_path`` is path to the actual XML + architecture file + + For Example following code shows how to define a benchmarks, + with single file multiple files and files added from specific directory. + + .. code-block:: text + + [BENCHMARKS] + # To declare single benchmark file + bench_design1=${BENCH_PATH}/design/top.v + + # To declare multiple benchmark file + bench_design2=${BENCH_PATH}/design/top.v,${BENCH_PATH}/design/sub_module.v + + # To add all files in specific directory to the benchmark + bench_design3=${BENCH_PATH}/design/top.v,${BENCH_PATH}/design/lib/*.v + +.. note:: + ``bench_label`` is referred again in ``Synthesis_Param`` section to + provide addional information about benchmark + +Synthesis Parameter Sections +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + User can define extra parameters for each benchmark defined in the + ``BENCHMARKS`` sections. + +.. option:: bench_top= + + This defines the Top Level module name for ``bench_label`` benchmark. + By default, the top level module name is cosidereed as a ``top``. + +.. option:: bench_yosys_tmpl= + + [TODO] + +.. option:: bench_chan_width= + + In case of running fixed channel width routing for each benchmark, + this option defines the channel width to be used for ``bench_label`` + benchmark + +.. option:: bench_act= + + In case of running ``blif_vpr_flow`` this option provides the activity files + to be used to generate testbench for ``bench_label`` benchmark + +.. option:: bench_verilog= + + In case of running ``blif_vpr_flow`` with verification this option provides + the source verilog design for ``bench_label`` benchmark to be used + while verification. + +Script Parameter Sections +^^^^^^^^^^^^^^^^^^^^^^^^^ +The script parameter section lists set of commnad line pararmeters to be passed to :ref:`run_fpga_flow` script. The section name is defines as ``SCRIPT_PARAM_`` where `parameter_set_label` can be any word without white spaces. +The section is referred with ``parameter_set_label`` in final result file. + +For example following code Specifies the two sets (``Fixed_Routing_30`` and ``Fixed_Routing_50``) of :ref:`run_fpga_flow` arguments. + +.. code-block:: text + + [SCRIPT_PARAM_Fixed_Routing_30] + # Execute fixed routing with channel with 30 + fix_route_chan_width=30 + + [SCRIPT_PARAM_Fixed_Routing_50] + # Execute fixed routing with channel with 50 + fix_route_chan_width=50 + +Example Task Configuration File +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: text + + [GENERAL] + spice_output=false + verilog_output=false + power_analysis = true + power_tech_file = ${PATH:TECH_PATH}/winbond90nm/winbond90nm_power_properties.xml + timeout_each_job = 20*60 + + [ARCHITECTURES] + arch0=${PATH:ARCH_PATH}/winbond90/k6_N10_rram_memory_bank_SC_winbond90.xml + + [BENCHMARKS] + bench0=${PATH:BENCH_PATH}/MCNC_Verilog/s298/s298.v + bench1=${PATH:BENCH_PATH}/MCNC_Verilog/elliptic/elliptic.v + + [SYNTHESIS_PARAM] + bench0_top = s298 + bench1_top = elliptic + + [SCRIPT_PARAM_Slack_30] + min_route_chan_width=1.3 + + [SCRIPT_PARAM_Slack_80] + min_route_chan_width=1.8 + diff --git a/openfpga_flow/scripts/run_fpga_task.py b/openfpga_flow/scripts/run_fpga_task.py index 04babac98..8125398b3 100644 --- a/openfpga_flow/scripts/run_fpga_task.py +++ b/openfpga_flow/scripts/run_fpga_task.py @@ -160,6 +160,7 @@ def generate_each_task_actions(taskname): GeneralSection = task_conf["GENERAL"] # Check if specified architecture files exist + # TODO Store it as a dictionary and take reference from the key archfile_list = [] for _, arch_file in task_conf["ARCHITECTURES"].items(): arch_full_path = arch_file