From 933de5e09e0ffb88d2d145fdc9de777cd3bcfc2f Mon Sep 17 00:00:00 2001 From: tangxifan Date: Mon, 10 Jun 2024 10:26:06 -0700 Subject: [PATCH 1/6] [ci] revert back to original checkout submodule strategy, as sockpp submodule link is updated in vtr --- .github/workflows/build.yml | 16 ---------------- .github/workflows/docker.yml | 4 ---- 2 files changed, 20 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index b757bebd7..894804b0e 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -119,8 +119,6 @@ jobs: - name: Checkout OpenFPGA repo uses: actions/checkout@v4 - with: - submodules: recursive - name: Install dependencies run: sudo bash ./.github/workflows/install_dependencies_build_${{ matrix.config.dependency_version }}.sh @@ -217,8 +215,6 @@ jobs: - name: Checkout OpenFPGA repo uses: actions/checkout@v4 - with: - submodules: recursive - name: Install dependencies run: sudo bash ./.github/workflows/install_dependencies_build_${{ matrix.config.dependency_version }}.sh @@ -265,8 +261,6 @@ jobs: - name: Checkout OpenFPGA repo uses: actions/checkout@v4 - with: - submodules: recursive - name: Install dependencies run: sudo bash ./.github/workflows/install_dependencies_build_${{ matrix.config.dependency_version }}.sh @@ -313,8 +307,6 @@ jobs: - name: Checkout OpenFPGA repo uses: actions/checkout@v4 - with: - submodules: recursive - name: Install dependencies run: | @@ -367,8 +359,6 @@ jobs: - name: Checkout OpenFPGA repo uses: actions/checkout@v4 - with: - submodules: recursive - name: Install dependencies run: | @@ -406,8 +396,6 @@ jobs: - name: Checkout OpenFPGA repo uses: actions/checkout@v4 - with: - submodules: recursive - name: Download a built artifacts uses: actions/download-artifact@v2 with: @@ -461,8 +449,6 @@ jobs: - name: Checkout OpenFPGA repo uses: actions/checkout@v4 - with: - submodules: recursive - name: Download a built artifacts uses: actions/download-artifact@v2 with: @@ -521,8 +507,6 @@ jobs: - name: Checkout OpenFPGA repo uses: actions/checkout@v4 - with: - submodules: recursive - name: ${{matrix.config.name}}_GCC-11_(Ubuntu 22.04) shell: bash diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index dfa73fb4a..bfcfa8641 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -32,8 +32,6 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 - with: - submodules: recursive - name: Set up QEMU uses: docker/setup-qemu-action@v1 - name: Set up Docker Buildx @@ -77,8 +75,6 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 - with: - submodules: recursive - name: Set up QEMU uses: docker/setup-qemu-action@v1 - name: Set up Docker Buildx From 3955c802577566313608c2f52b86fceff0808b13 Mon Sep 17 00:00:00 2001 From: tangxifan Date: Mon, 10 Jun 2024 10:42:29 -0700 Subject: [PATCH 2/6] [doc] now add tips/notes to readme. Update broken links --- README.md | 15 +- docs/source/dev_manual/ci.rst | 194 +++++++++++++++ .../contributor_guidelines/general_rules.rst | 44 ++++ .../contributor_guidelines/index.rst | 11 + .../naming_convention.rst | 224 ++++++++++++++++++ docs/source/dev_manual/index.rst | 2 + 6 files changed, 484 insertions(+), 6 deletions(-) create mode 100644 docs/source/dev_manual/ci.rst create mode 100644 docs/source/dev_manual/contributor_guidelines/general_rules.rst create mode 100644 docs/source/dev_manual/contributor_guidelines/index.rst create mode 100644 docs/source/dev_manual/contributor_guidelines/naming_convention.rst diff --git a/README.md b/README.md index 0b4bb8fd6..9cf09dc9d 100644 --- a/README.md +++ b/README.md @@ -11,16 +11,19 @@ Version: see [`VERSION.md`](VERSION.md) The award-winning OpenFPGA framework is the **first open-source FPGA IP generator with silicon proofs** supporting highly-customizable FPGA architectures. OpenFPGA provides complete EDA support for customized FPGAs, including Verilog-to-bitstream generation and self-testing verification. OpenFPGA opens the door to democratizing FPGA technology and EDA techniques with agile prototyping approaches and constantly evolving EDA tools for chip designers and researchers. -**If this is your first time working with OpenFPGA, we strongly **recommend you watch the** [introduction video about OpenFPGA](https://youtu.be/ocODUGcYGqo)** +[!TIP] +If this is your first time working with OpenFPGA, we strongly recommend you watch the [introduction video about OpenFPGA](https://youtu.be/ocODUGcYGqo) A quick overview of OpenFPGA tools can be found [**here**](https://openfpga.readthedocs.io/en/master/tutorials/getting_started/tools/). We also recommend potential users check out the summary of [**technical capabilities**](https://openfpga.readthedocs.io/en/master/overview/tech_highlights/#) before compiling. -**Before asking for help, please checkout the** [Frequently Asked Questions](https://github.com/lnis-uofu/OpenFPGA/discussions/937) +[!TIP] +Before asking for help, please checkout the [Frequently Asked Questions](https://github.com/lnis-uofu/OpenFPGA/discussions/937) ## Compilation -**A tutorial **video about **how to compile** can be** found [here](https://youtu.be/F9sMRmDewM0)** +[!NOTE] +A tutorial video about how to compile can be found [here](https://youtu.be/F9sMRmDewM0) Detailed guidelines are available at [**compilation guidelines**](https://openfpga.readthedocs.io/en/master/tutorials/getting_started/compile/). Before starting, we strongly recommend you read the required dependencies and ensure that they are correctly installed. @@ -36,7 +39,7 @@ You can find a set of [tutorials](https://openfpga.readthedocs.io/en/master/tuto ## Backward Compatibility -If you were using an old version of OpenFPGA and are now interested to move to the latest version, please check out the [developer guidelines](https://openfpga.readthedocs.io/en/master/dev_manual/back_compatibile). +If you were using an old version of OpenFPGA and are now interested to move to the latest version, please check out the [developer guidelines](https://openfpga.readthedocs.io/en/master/dev_manual/back_compatible/). ## License @@ -54,8 +57,8 @@ Bibtex: @ARTICLE{9098028, author={Tang, Xifan and Giacomin, Edouard and Chauviere, Baudouin and Alacchi, Aurélien and Gaillardon, Pierre-Emmanuel}, journal={IEEE Micro}, title={OpenFPGA: An Open-Source Framework for Agile Prototyping Customizable FPGAs}, year={2020}, volume={40}, number={4}, pages={41-48}, doi={10.1109/MM.2020.2995854}} ``` -A list of related publications can be found [here](https://openfpga.readthedocs.io/en/master/reference/). +A list of related publications can be found [here](https://openfpga.readthedocs.io/en/master/appendix/reference/). ## Contributing to OpenFPGA -Please read the [contributor guidelines](https://openfpga.readthedocs.io/en/master/dev_manual/contributor_guide) if you would like to contribute to OpenFPGA. +Please read the [contributor guidelines](https://openfpga.readthedocs.io/en/master/dev_manual/contributor_guide/) if you would like to contribute to OpenFPGA. diff --git a/docs/source/dev_manual/ci.rst b/docs/source/dev_manual/ci.rst new file mode 100644 index 000000000..acae64c6b --- /dev/null +++ b/docs/source/dev_manual/ci.rst @@ -0,0 +1,194 @@ +.. _developer_ci: + +Continous Integration +===================== + +Motivation +---------- + +Continous Integration (CI) systems are built to ensure that input and output files of each teams are + +- Correct +- Reproducable +- Consistent with other teams + +CI system is automatically triggered on + +- Main branch: the master branch of the codebase +- A pull request on main branch + +Workflows +--------- + +Principles +^^^^^^^^^^ + +Continous Integration system consists a number of workflows, each of which is designed to validate a specific aspect of the codebase. +For the work of each team, there is at least 1 dedicated workflow. + +Workflows can categorized in two types + +.. option:: Generation flow + + Such type of workflow is designed to ensure that golden files (netlists, bitstreams, etc.) are reproduciable. + A generation workflow consists of three steps: + + - Detect changes on input files, e.g., architecture files, IPs and related scripts. + + - If no changes detected, the workflow ends, since the golden outputs are not changed in a pull request + - If any changes are detected, the workflow will continue to the next steps + + - Regenerate golden files by calling scripts. By the end of this step, it will compare the newly generated files with the golden reference (current branch) + - If there are no changes, the workflow ends. + - If any changes on golden reference are detected, this will error out. It means that the current golden reference are not reproduciable. + + .. warning:: If any changes on golden references are detected, code review has to be enforced. Ensure that all the teams impacted agree on the changes. + +.. option:: Validation flow + + Such type of workflow is designed to verify the correctness of golden files + A validation workflow consists of three steps: + + - Detect changes on golden reference (some pull requests update golden references) + + - If no changes detected, the workflow ends. There is no need to validate the correctness of the golden reference (previous pull request should already do so). + - If any changes are detected, the workflow will continue to the next steps + + - Run validation by calling scripts. For example, verification may call HDL simulations to verify the correctness of netlists. + - If the new golden reference passes all the tests, this will end. + - If the new golden reference fails any test, this will error out. It means that the current golden reference can not meet basic requirements. + + .. warning:: If any validation flow failed, the pull request cannot be merged in general. + +.. _developer_ci_workflow_check_tool_version: + +Check Tool Version +^^^^^^^^^^^^^^^^^^ + +The workflow aims to validate the following: + +- All the tools meet the expected versions as documented + +.. warning:: **This workflow is essential!** If it fails, there is a problem in infrastructure. + +.. _developer_ci_workflow_netlist_generation: + +Netlist Generation +^^^^^^^^^^^^^^^^^^ + +As illustrated in Fig. :numref:`fig_ci_workflows_netlist_generation`, the workflow aims to validate the following: + +- RTL netlists are reproduciable by OpenFPGA and architecture files +- Gate-level netlists are reproduciable by OpenFPGA, architecture files and related scripts + + +.. _fig_ci_workflows_netlist_generation: + +.. figure:: ./figures/ci_workflows_netlist_generation.svg + :width: 100% + + Decision tree of netlist generation workflow + +.. _developer_ci_workflow_bitstream_generation: + +Bitstream Generation +^^^^^^^^^^^^^^^^^^^^ + +As illustrated in Fig. :numref:`fig_ci_workflows_bitstream_generation`, the workflow aims to validate the following: + +- Bitstream files are reproduciable by OpenFPGA, benchmarks and architecture files + +.. _fig_ci_workflows_bitstream_generation: + +.. figure:: ./figures/ci_workflows_bitstream_generation.svg + :width: 100% + + Decision tree of bitstream generation workflow + +.. _developer_ci_workflow_testbench_generation: + +Testbench Generation +^^^^^^^^^^^^^^^^^^^^ + +As illustrated in Fig. :numref:`fig_ci_workflows_testbench_generation`, the workflow aims to validate the following: + +- Testbench files are reproduciable by OpenFPGA, benchmarks and architecture files + +.. _fig_ci_workflows_testbench_generation: + +.. figure:: ./figures/ci_workflows_testbench_generation.svg + :width: 100% + + Decision tree of testbench generation workflow + +.. _developer_ci_workflow_rtl_verification: + +RTL Verification +^^^^^^^^^^^^^^^^ + +As illustrated in Fig. :numref:`fig_ci_workflows_rtl_verification`, the workflow aims to validate the following: + +- RTL netlists can pass all the design verification tests. + +.. _fig_ci_workflows_rtl_verification: + +.. figure:: ./figures/ci_workflows_rtl_verification.svg + :width: 100% + + Decision tree of RTL verification workflow + + +Useful Labels of Pull Requests +------------------------------ + +Continous integration is triggered conditionally to avoid high traffic in computing machines. +Users can add the following labels in pull requests, to force running some tests: + +.. option:: force_netlist_generation + + Force the run of netlist generation workflow. See details in :ref:`developer_ci_workflow_netlist_generation` + +.. option:: force_bitstream_generation + + Force the run of bitstream generation workflow. See details in :ref:`developer_ci_workflow_bitstream_generation` + +.. option:: force_testbench_generation + + Force the run of testbench generation workflow. See details in :ref:`developer_ci_workflow_testbench_generation` + +.. option:: force_rtl_full_simulation + + Force the run of full testbench simulation for RTL netlists. See details in :ref:`developer_ci_workflow_rtl_verification` + +.. option:: force_rtl_preconfig_simulation + + Force the run of preconfigured testbench simulation for RTL netlists. See details in :ref:`developer_ci_workflow_rtl_verification` + +.. option:: force_gl_full_simulation + + Force the run of full testbench simulation for gate-level netlists. See details in :ref:`developer_ci_workflow_rtl_verification` + +.. option:: force_gl_preconfig_simulation + + Force the run of preconfigured testbench simulation for gate-level netlists. See details in :ref:`developer_ci_workflow_rtl_verification` + +CI Runners +---------- + +Workflows are executed on two type of runners (computers) + +- Github-hosted runners + +- Self-hosted runners + +Github-Hosted Runners +^^^^^^^^^^^^^^^^^^^^^ + +All the detect-changes parts of workflow are executed here because they do not require in-house tools + +Self-Hosted Runners +^^^^^^^^^^^^^^^^^^^ + +Most generation/validation workflow are executed here because they require in-house tools + +Currently, the self-hosted runners are on the ``eda01``, ``eda02`` and ``eda03`` workstation diff --git a/docs/source/dev_manual/contributor_guidelines/general_rules.rst b/docs/source/dev_manual/contributor_guidelines/general_rules.rst new file mode 100644 index 000000000..3df8e658b --- /dev/null +++ b/docs/source/dev_manual/contributor_guidelines/general_rules.rst @@ -0,0 +1,44 @@ +.. _developer_contributor_guidelines_general_rules: + +General Rules +============= + +Motivation +---------- +Github projects involve many parties with different interests. +It is necessary to establish rules to + +- guarantee the quality of each pull request by establishing a standard +- code review for each pull request is straightforward +- contributors have confidence when submitting changes + +Create Pull requests +-------------------- + +- Contributors should state clearly their motivation and the principles of code changes in each pull request +- Contributors should be active in resolving conflicts with other contributors as well as maintainers. In principle, all the maintainers want every pull request in and are looking for reasons to approve it. +- Each pull request should pass all the existing tests in CI (See :ref:`developer_contributor_guidelines_checkin_system` for details). Otherwise, it should not be merged unless you get a waiver from all the maintainers. +- Contributors should not modify any codes/tests which are unrelated to the scope of their pull requests. +- The size of each pull request should be small. Large pull request takes weeks to be merged. The recommend size of pull request is up to 500 lines of codes changes. If you have one large file, this can be waived. However, the number of files to be changed should be as small as possible. + + .. note:: For large pull requests, it is strongly recommended that contributors should talk to maintainers first or create an issue on the Github. Contributors should clearly define the motivation, detailed technical plan as well as deliverables. Through discussions, the technical plan may be requested to change. Please do not start code changes blindly before the technical plan is approved. + +- For any new feature/functionality to be added, there should be + + - Dedicated test cases in CI which validates its correctness + - An update on the documentation, if it changes user interface + - Provide sufficient code comments to ease the maintenance + +.. _developer_contributor_guidelines_checkin_system: + +Check-in System +--------------- + +.. seealso:: The check-in system is based on continous integration (CI). See details in :ref:`developer_ci` + +The check-in system aims to offer a standardized way to + +- ensure quailty of each contribution +- resolve conflicts between teams + +It is designed for efficient communication between teams. diff --git a/docs/source/dev_manual/contributor_guidelines/index.rst b/docs/source/dev_manual/contributor_guidelines/index.rst new file mode 100644 index 000000000..0fa7b108b --- /dev/null +++ b/docs/source/dev_manual/contributor_guidelines/index.rst @@ -0,0 +1,11 @@ +.. _developer_contributor_guidelines: + +Contributor Guidelines +====================== + +.. toctree:: + :maxdepth: 2 + + general_rules + + naming_convention diff --git a/docs/source/dev_manual/contributor_guidelines/naming_convention.rst b/docs/source/dev_manual/contributor_guidelines/naming_convention.rst new file mode 100644 index 000000000..34b775654 --- /dev/null +++ b/docs/source/dev_manual/contributor_guidelines/naming_convention.rst @@ -0,0 +1,224 @@ +.. _developer_naming_convention: + +Naming Convention +================= + +.. _developer_naming_convention_cell_names: + +Cell Names +---------- + +.. warning:: This is a different concept than the cell names in :ref:`developer_naming_convention_ff_model_names`! + +.. note:: we refer to standard cell wrapper here. Wrappers are built to make netlists portable between PDKs as well as across standard cell libraries in a PDK. + +For code readability, the cell name should follow the convention +:: + _ + +.. option:: Cell_Function + + Name of logic function, e.g., AND2, XNOR3, etc. + +.. option:: Set_Features + + This is mainly for sequential cells, e.g., D-type flip-flops. If a cell contains a set signal, its existence and polarity must be inferreable by the cell name. The available options are + + - S: Asynchronous active-high set + - SYNS: Synchronous active-hight set + - SN: Asynchronous active-low set + - SYNSN: Synchronous active-low set + + .. note:: For cells without set, this keyword should be empty + +.. option:: Reset_Features + + This is mainly for sequential cells, e.g., D-type flip-flops. If a cell contains a reset signal, its existence and polarity must be inferreable by the cell name. The available options are + + - R: Asynchronous active-high reset + - SYNR: Synchronous active-hight reset + - RN: Asynchronous active-low reset + - SYNRN: Synchronous active-low reset + + .. note:: For cells without reset, this keyword should be empty + +.. option:: Output_Features + + This is mainly for sequential cells, e.g., D-type flip-flops. + + - If not specified, the sequential cell contains a pair of differential outputs, e.g., ``Q`` and ``QN`` + - If specified, the sequential cell only contains single output, e.g., ``Q`` + + The available options are + + - Q: single output which is positive + - QN: single ouput which is negative + + .. note:: For cells without reset, this keyword should be empty + +.. option:: Drive_Strength + + This is to specify the drive strength of a cell + + - If not specified, we assume minimum drive strength, i.e., ``D0``. + - If specified, we expect a format of ``D``, where the integer indicates the drive strength + +.. option:: Wrapper + + This is to specify if the cell is a wrapper of an existing standard cell + + - If not specified, we assume this cell contains RTL + - If specified, we assume this cell is a wrapper of an existing standard cell + +A quick example +:: + NAND2D4_WRAPPER + +represents a wrapper for a standard cell that is a 2-input NAND gate with a drive strength of 4 + +Another example +:: + SDFFSSYNRNQ + +represents a scan-chain flip-flop which contains + + - Asynchronous active-high set + - Synchronous active-low reset + - Single output + +Pin Names +--------- + +.. note:: Please use lowercase as much as you can + +For code readability, the pin name should follow the convention +:: + _ + + +.. option:: Pin_Name + + Represents the pin name + +.. option:: Polarity + + Represents polarity of the pin, it can be + + - ``n`` denotes a negative-enable (active_low) signal + + .. note:: When not specified, by default we assume this is a postive-enable (active-high) signal + +.. option:: Direction + + Represents the direction of a pin, it can be + + - ``i`` denotes an input signal + - ``o`` denotes an output signal + +A quick example +:: + clk_ni + +represents an input clock signal which is negative-enable + +Another example +:: + q_no + +represents an output Q signal which is negative to the input + +.. _developer_naming_convention_ff_model_names: + +Flip-flop Model Names +--------------------- + +.. warning:: This is a different concept than the cell names in :ref:`developer_naming_convention_cell_names`! + +.. note:: we refer to virtual cell model (used by VPR and Yosys for cell mapping) here. + +For code readability, D-type flip-flop model names should follow the convention +:: + dff + +.. option:: Sync_Features + + Represents if the reset/set is synchronous or asynchronous to the clock, it can be + + - ``s`` denotes a synchronous behavior + - an empty string "" denotes an asynchronous behavior, e.g., ``ffr`` + +.. option:: Trigger_Type + + Represents if the flip-flop is triggered by rising edge or falling edge of a clock, it can be + + - ``n`` means triggered by failling edge + - an empty string "" means triggered by rising edge, e.g., ``ff`` + +.. option:: Set_Type + + Represents if the flip-flop has a set and the polarity of the set, it can be + + - ``s`` means that the flip-flop has an active-high set pin + - ``sn`` means that the flip-flop has an active-low set pin + - an empty string "" means the flip-flop does not have a set pin, e.g., ``ff`` + +.. option:: Reset_Type + + Represents if the flip-flop has a reset and the polarity of the reset, it can be + + - ``r`` means that the flip-flop has an active-high reset pin + - ``rn`` means that the flip-flop has an active-low reset pin + - an empty string "" means the flip-flop does not have a reset pin, e.g., ``ff`` + + +A quick example +:: + ffnrn + +represents a flip-flop + +- triggered by falling edge +- with an asynchronous active-low reset + +Another example +:: + sffs + +represents a flip-flop + +- triggered by rising edge +- with a synchronous active-high set + +.. _developer_naming_convention_mux_model_names: + +Multiplexer Model Names +----------------------- + +.. warning:: This is a different concept than the cell names in :ref:`developer_naming_convention_cell_names`! + +.. note:: Here, we refer to the circuit model name used in OpenFPGA architecture file. + +For code readability, a routing multiplexer circuit model name should follow the convention +:: + _mux_ + +.. option:: Location + + Represents the location of the routing multiplexers, it can be + + - ``cb`` denotes a routing multiplexer in a connection block + - ``sb`` denotes a routing multiplexer in a switch block + - ``pb`` denotes a routing multiplexer in a programmable block + +.. option:: Load + + Represents the output load condition of the routing multiplexers, it can be + + - ``highload`` means that the routing multiplexer has to drive a very high capacitive load, which potentially requires a big buffer at output + - an empty string "" means the routing multiplexer requires only a typical buffer size. + +A quick example +:: + pb_mux_highload + +represents a routing multiplexer used in a programmable block which drives a high capacitive load diff --git a/docs/source/dev_manual/index.rst b/docs/source/dev_manual/index.rst index 6f5fd58ba..0e6695b7d 100644 --- a/docs/source/dev_manual/index.rst +++ b/docs/source/dev_manual/index.rst @@ -8,6 +8,8 @@ contributor_guidelines + ci + cicd_setup regression_tests From 5dcaab98bfc6124257a52f5a150ced6edbf89e8a Mon Sep 17 00:00:00 2001 From: tangxifan Date: Mon, 10 Jun 2024 10:43:45 -0700 Subject: [PATCH 3/6] [doc] format --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 9cf09dc9d..a66ddc216 100644 --- a/README.md +++ b/README.md @@ -11,19 +11,19 @@ Version: see [`VERSION.md`](VERSION.md) The award-winning OpenFPGA framework is the **first open-source FPGA IP generator with silicon proofs** supporting highly-customizable FPGA architectures. OpenFPGA provides complete EDA support for customized FPGAs, including Verilog-to-bitstream generation and self-testing verification. OpenFPGA opens the door to democratizing FPGA technology and EDA techniques with agile prototyping approaches and constantly evolving EDA tools for chip designers and researchers. -[!TIP] -If this is your first time working with OpenFPGA, we strongly recommend you watch the [introduction video about OpenFPGA](https://youtu.be/ocODUGcYGqo) +> [!TIP] +> If this is your first time working with OpenFPGA, we strongly recommend you watch the [introduction video about OpenFPGA](https://youtu.be/ocODUGcYGqo) A quick overview of OpenFPGA tools can be found [**here**](https://openfpga.readthedocs.io/en/master/tutorials/getting_started/tools/). We also recommend potential users check out the summary of [**technical capabilities**](https://openfpga.readthedocs.io/en/master/overview/tech_highlights/#) before compiling. -[!TIP] -Before asking for help, please checkout the [Frequently Asked Questions](https://github.com/lnis-uofu/OpenFPGA/discussions/937) +> [!TIP] +> Before asking for help, please checkout the [Frequently Asked Questions](https://github.com/lnis-uofu/OpenFPGA/discussions/937) ## Compilation -[!NOTE] -A tutorial video about how to compile can be found [here](https://youtu.be/F9sMRmDewM0) +> [!NOTE] +> A tutorial video about how to compile can be found [here](https://youtu.be/F9sMRmDewM0) Detailed guidelines are available at [**compilation guidelines**](https://openfpga.readthedocs.io/en/master/tutorials/getting_started/compile/). Before starting, we strongly recommend you read the required dependencies and ensure that they are correctly installed. From e6784fdf6c2377da49205bb5da34bd06ad2e23b4 Mon Sep 17 00:00:00 2001 From: tangxifan Date: Mon, 10 Jun 2024 10:47:22 -0700 Subject: [PATCH 4/6] [doc] merge cicd into ci section --- docs/source/dev_manual/ci.rst | 189 ++++++++++++-------------- docs/source/dev_manual/cicd_setup.rst | 123 ----------------- docs/source/dev_manual/index.rst | 2 - 3 files changed, 89 insertions(+), 225 deletions(-) delete mode 100644 docs/source/dev_manual/cicd_setup.rst diff --git a/docs/source/dev_manual/ci.rst b/docs/source/dev_manual/ci.rst index acae64c6b..043edb1db 100644 --- a/docs/source/dev_manual/ci.rst +++ b/docs/source/dev_manual/ci.rst @@ -60,135 +60,124 @@ Workflows can categorized in two types .. warning:: If any validation flow failed, the pull request cannot be merged in general. -.. _developer_ci_workflow_check_tool_version: +CI/CD setup +----------- -Check Tool Version -^^^^^^^^^^^^^^^^^^ - -The workflow aims to validate the following: - -- All the tools meet the expected versions as documented - -.. warning:: **This workflow is essential!** If it fails, there is a problem in infrastructure. - -.. _developer_ci_workflow_netlist_generation: - -Netlist Generation -^^^^^^^^^^^^^^^^^^ - -As illustrated in Fig. :numref:`fig_ci_workflows_netlist_generation`, the workflow aims to validate the following: - -- RTL netlists are reproduciable by OpenFPGA and architecture files -- Gate-level netlists are reproduciable by OpenFPGA, architecture files and related scripts +OpenFPGA implements CI/CD system using Github actions. +The following figure shows the Actions implements flow. +The source building is skipped if there are changes only in ``openfpga_flow`` or ``docs`` directory, +in which case the docker image compiled for the latest master branch is used for running a regression. -.. _fig_ci_workflows_netlist_generation: +.. graphviz:: + :align: center -.. figure:: ./figures/ci_workflows_netlist_generation.svg - :width: 100% + digraph G { + node [fontname = "Handlee"]; + edge [fontname = "Handlee"]; + Trigger [ + label = "Action triggered" + ]; - Decision tree of netlist generation workflow + masterCompare [ + label = "Diff with current master" + ]; -.. _developer_ci_workflow_bitstream_generation: + Build [ + label = "Changes only in\n openfpga_flow/doc?" + shape = diamond + ]; -Bitstream Generation -^^^^^^^^^^^^^^^^^^^^ + BuildDocker [ + label = "Run build regression test\nBuild docker images" + shape = box + ]; -As illustrated in Fig. :numref:`fig_ci_workflows_bitstream_generation`, the workflow aims to validate the following: + PushDockersCond [ + label = "Is merge\non master?" + shape = diamond + ]; -- Bitstream files are reproduciable by OpenFPGA, benchmarks and architecture files + PushDockers [ + label = "Push docker Images\n(maintain compiled binary\nin docker + Example tasks)" + shape = box + ]; -.. _fig_ci_workflows_bitstream_generation: + RunRegression [ + label = "Run functional regression test" + shape = box + ]; -.. figure:: ./figures/ci_workflows_bitstream_generation.svg - :width: 100% + Trigger ->masterCompare; + masterCompare ->Build; + Build -> BuildDocker [ label = "No" ]; + BuildDocker -> PushDockersCond; + edge[weight=0.5] Build -> RunRegression [ label = "Yes" ]; + edge[weight=10] PushDockersCond -> RunRegression [ label = "No" ]; + PushDockersCond -> PushDockers [ label = "Yes" ]; + edge[weight=2] PushDockers -> RunRegression; - Decision tree of bitstream generation workflow - -.. _developer_ci_workflow_testbench_generation: - -Testbench Generation -^^^^^^^^^^^^^^^^^^^^ - -As illustrated in Fig. :numref:`fig_ci_workflows_testbench_generation`, the workflow aims to validate the following: - -- Testbench files are reproduciable by OpenFPGA, benchmarks and architecture files - -.. _fig_ci_workflows_testbench_generation: - -.. figure:: ./figures/ci_workflows_testbench_generation.svg - :width: 100% - - Decision tree of testbench generation workflow - -.. _developer_ci_workflow_rtl_verification: - -RTL Verification -^^^^^^^^^^^^^^^^ - -As illustrated in Fig. :numref:`fig_ci_workflows_rtl_verification`, the workflow aims to validate the following: - -- RTL netlists can pass all the design verification tests. - -.. _fig_ci_workflows_rtl_verification: - -.. figure:: ./figures/ci_workflows_rtl_verification.svg - :width: 100% - - Decision tree of RTL verification workflow + { + rank=same; + PushDockersCond PushDockers; + }; + } -Useful Labels of Pull Requests ------------------------------- +| -Continous integration is triggered conditionally to avoid high traffic in computing machines. -Users can add the following labels in pull requests, to force running some tests: -.. option:: force_netlist_generation +.. option:: Build regression test - Force the run of netlist generation workflow. See details in :ref:`developer_ci_workflow_netlist_generation` + The OpenFPGA source is compiled with the following set of compilers. -.. option:: force_bitstream_generation + #. gcc-7 + #. gcc-8 + #. gcc-9 + #. gcc-10 + #. gcc-11 + #. clang-6 + #. clang-7 + #. clang-8 + #. clang-10 - Force the run of bitstream generation workflow. See details in :ref:`developer_ci_workflow_bitstream_generation` + The docker images for these build environment are available on `github packages `_. -.. option:: force_testbench_generation +.. option:: Functional regression test - Force the run of testbench generation workflow. See details in :ref:`developer_ci_workflow_testbench_generation` + OpenFPGA maintains a set of functional tests to validate the different functionality. + The test are broadly catagories into ``basic_reg_test``, ``fpga_verilog_reg_test``, + ``fpga_bitstream_reg_test``, ``fpga_sdc_reg_test``, and ``fpga_spice_reg_test``. + A functional regression test is run for every commit on every branch. -.. option:: force_rtl_full_simulation - Force the run of full testbench simulation for RTL netlists. See details in :ref:`developer_ci_workflow_rtl_verification` +How to debug failed regression test +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In case the ``functional regression test`` fails, +the actions script will collect all ``.log`` files from +the task directory and upload as a artifacts on github storage. +These artifacts can be downloaded from the github website actions tab, for more reference follow `this `_ article. -.. option:: force_rtl_preconfig_simulation +**NOTE** : The retention time of these artifacts is 1 day, +so in case user want to reserve the failure log for longer duration back it up locally - Force the run of preconfigured testbench simulation for RTL netlists. See details in :ref:`developer_ci_workflow_rtl_verification` +Release Docker Images +^^^^^^^^^^^^^^^^^^^^^^ -.. option:: force_gl_full_simulation +.. option:: ghcr.io/lnis-uofu/openfpga-master:latest - Force the run of full testbench simulation for gate-level netlists. See details in :ref:`developer_ci_workflow_rtl_verification` + This is a bleeding-edge release from the current master branch of OpenFPGA. + It is updated automatically whenever there is activity on the master branch. + Due to high development activity, we recommend the user to use the bleeding-edge version to get access to all new features and report an issue in case there are any bugs. -.. option:: force_gl_preconfig_simulation - Force the run of preconfigured testbench simulation for gate-level netlists. See details in :ref:`developer_ci_workflow_rtl_verification` +CI after cloning repository +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +If you clone the repository the CI setup will still function, except the based images are still pulled from "lnis-uofu" repository and the master branch +of cloned repo will not push final docker image to any repository . -CI Runners ----------- +**In case you want to host your own copies of OpenFPGA base images** and final release create a github secret variable with name ``DOCKER_REPO`` and set it to ``true``. This will make ci script to download base images from your own repo packages, and upload final release to the same. -Workflows are executed on two type of runners (computers) +**If you don not want to use docker images based regression test** and like to compile all the binaries for each CI run. You can set ``IGNORE_DOCKER_TEST`` secrete variable to ``true``. -- Github-hosted runners - -- Self-hosted runners - -Github-Hosted Runners -^^^^^^^^^^^^^^^^^^^^^ - -All the detect-changes parts of workflow are executed here because they do not require in-house tools - -Self-Hosted Runners -^^^^^^^^^^^^^^^^^^^ - -Most generation/validation workflow are executed here because they require in-house tools - -Currently, the self-hosted runners are on the ``eda01``, ``eda02`` and ``eda03`` workstation +.. note:: Once you add ``DOCKER_REPO`` variable, you need to generate base images. To do this trigger manual workflow ``Build docker CI images`` diff --git a/docs/source/dev_manual/cicd_setup.rst b/docs/source/dev_manual/cicd_setup.rst deleted file mode 100644 index 92609ccd3..000000000 --- a/docs/source/dev_manual/cicd_setup.rst +++ /dev/null @@ -1,123 +0,0 @@ -.. dev_manual_cicd_setup:: - -CI/CD setup ------------ - -OpenFPGA implements CI/CD system using Github actions. -The following figure shows the Actions implements flow. -The source building is skipped if there are changes only in ``openfpga_flow`` or ``docs`` directory, -in which case the docker image compiled for the latest master branch is used for running a regression. - - -.. graphviz:: - :align: center - - digraph G { - node [fontname = "Handlee"]; - edge [fontname = "Handlee"]; - Trigger [ - label = "Action triggered" - ]; - - masterCompare [ - label = "Diff with current master" - ]; - - Build [ - label = "Changes only in\n openfpga_flow/doc?" - shape = diamond - ]; - - BuildDocker [ - label = "Run build regression test\nBuild docker images" - shape = box - ]; - - PushDockersCond [ - label = "Is merge\non master?" - shape = diamond - ]; - - PushDockers [ - label = "Push docker Images\n(maintain compiled binary\nin docker + Example tasks)" - shape = box - ]; - - RunRegression [ - label = "Run functional regression test" - shape = box - ]; - - Trigger ->masterCompare; - masterCompare ->Build; - Build -> BuildDocker [ label = "No" ]; - BuildDocker -> PushDockersCond; - edge[weight=0.5] Build -> RunRegression [ label = "Yes" ]; - edge[weight=10] PushDockersCond -> RunRegression [ label = "No" ]; - PushDockersCond -> PushDockers [ label = "Yes" ]; - edge[weight=2] PushDockers -> RunRegression; - - { - rank=same; - PushDockersCond PushDockers; - }; - } - - -| - - -.. option:: Build regression test - - The OpenFPGA source is compiled with the following set of compilers. - - #. gcc-7 - #. gcc-8 - #. gcc-9 - #. gcc-10 - #. gcc-11 - #. clang-6 - #. clang-7 - #. clang-8 - #. clang-10 - - The docker images for these build environment are available on `github packages `_. - -.. option:: Functional regression test - - OpenFPGA maintains a set of functional tests to validate the different functionality. - The test are broadly catagories into ``basic_reg_test``, ``fpga_verilog_reg_test``, - ``fpga_bitstream_reg_test``, ``fpga_sdc_reg_test``, and ``fpga_spice_reg_test``. - A functional regression test is run for every commit on every branch. - - -How to debug failed regression test -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In case the ``functional regression test`` fails, -the actions script will collect all ``.log`` files from -the task directory and upload as a artifacts on github storage. -These artifacts can be downloaded from the github website actions tab, for more reference follow `this `_ article. - -**NOTE** : The retention time of these artifacts is 1 day, -so in case user want to reserve the failure log for longer duration back it up locally - -Release Docker Images -^^^^^^^^^^^^^^^^^^^^^^ - -.. option:: ghcr.io/lnis-uofu/openfpga-master:latest - - This is a bleeding-edge release from the current master branch of OpenFPGA. - It is updated automatically whenever there is activity on the master branch. - Due to high development activity, we recommend the user to use the bleeding-edge version to get access to all new features and report an issue in case there are any bugs. - - -CI after cloning repository -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you clone the repository the CI setup will still function, except the based images are still pulled from "lnis-uofu" repository and the master branch -of cloned repo will not push final docker image to any repository . - -**In case you want to host your own copies of OpenFPGA base images** and final release create a github secret variable with name ``DOCKER_REPO`` and set it to ``true``. This will make ci script to download base images from your own repo packages, and upload final release to the same. - -**If you don not want to use docker images based regression test** and like to compile all the binaries for each CI run. You can set ``IGNORE_DOCKER_TEST`` secrete variable to ``true``. - -.. note:: Once you add ``DOCKER_REPO`` variable, you need to generate base images. To do this trigger manual workflow ``Build docker CI images`` diff --git a/docs/source/dev_manual/index.rst b/docs/source/dev_manual/index.rst index 0e6695b7d..0dbc77bb7 100644 --- a/docs/source/dev_manual/index.rst +++ b/docs/source/dev_manual/index.rst @@ -10,8 +10,6 @@ ci - cicd_setup - regression_tests tcl_api From 87a07fb111dda52b0fa5efb8e435af993919a2ea Mon Sep 17 00:00:00 2001 From: tangxifan Date: Mon, 10 Jun 2024 10:57:27 -0700 Subject: [PATCH 5/6] [doc] add missing links --- docs/source/dev_manual/index.rst | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/source/dev_manual/index.rst b/docs/source/dev_manual/index.rst index 0dbc77bb7..0a86d4b12 100644 --- a/docs/source/dev_manual/index.rst +++ b/docs/source/dev_manual/index.rst @@ -1,16 +1,22 @@ +.. _developer: + Developer Guidelines .. toctree:: - :maxdepth: 1 + :maxdepth: 2 version_number back_compatible - contributor_guidelines - ci regression_tests tcl_api + +.. toctree:: + :maxdepth: 2 + :caption: Contributor Guidelines + + contributor_guidelines/index From c05cc3989959bda977659f71194c8a520a103aee Mon Sep 17 00:00:00 2001 From: tangxifan Date: Mon, 10 Jun 2024 12:19:58 -0700 Subject: [PATCH 6/6] [ci] now enable cancel jobs in progress --- .github/workflows/build.yml | 4 ++++ .github/workflows/cell_lib_test.yml | 4 ++++ .github/workflows/docker.yml | 4 ++++ .github/workflows/format.yaml | 4 ++++ 4 files changed, 16 insertions(+) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 894804b0e..e3a223a24 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -7,6 +7,10 @@ on: schedule: - cron: "0 0 * * 0 " # weekly +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + # Environment variables env: # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.) diff --git a/.github/workflows/cell_lib_test.yml b/.github/workflows/cell_lib_test.yml index 3a472af3a..8ee9c47cc 100644 --- a/.github/workflows/cell_lib_test.yml +++ b/.github/workflows/cell_lib_test.yml @@ -7,6 +7,10 @@ on: schedule: - cron: "0 0 * * 0 " # weekly +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + # Multiple job to tests jobs: # Test the RTL compilation compatibility diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index bfcfa8641..ef77be6ed 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -7,6 +7,10 @@ env: DOCKER_REPO: ${{ secrets.DOCKER_REPO }} REPO_OWNER: ${{ github.repository_owner }} +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + jobs: change_detect: name: "Detect code changes" diff --git a/.github/workflows/format.yaml b/.github/workflows/format.yaml index e4c84320e..fc119f7eb 100644 --- a/.github/workflows/format.yaml +++ b/.github/workflows/format.yaml @@ -7,6 +7,10 @@ on: schedule: - cron: "0 0 * * 0 " # weekly +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + # Multiple job to tests jobs: change_detect: