[doc] now add tips/notes to readme. Update broken links
This commit is contained in:
tangxifan
parent
933de5e09e
commit
3955c80257
15
README.md
15
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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
.. _developer_contributor_guidelines:
|
||||
|
||||
Contributor Guidelines
|
||||
======================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
general_rules
|
||||
|
||||
naming_convention
|
||||
|
|
@ -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
|
||||
::
|
||||
<Cell_Function><Set_Features><Reset_Features><Output_Features><Drive_Strength>_<Wrapper>
|
||||
|
||||
.. 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<int>``, 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
|
||||
::
|
||||
<Pin_Name>_<Polarity><Direction>
|
||||
|
||||
|
||||
.. 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
|
||||
::
|
||||
<Sync_Type>dff<Trigger_Type><Set_Type><Reset_Type>
|
||||
|
||||
.. 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
|
||||
::
|
||||
<Location>_mux_<Load>
|
||||
|
||||
.. 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
|
||||
|
|
@ -8,6 +8,8 @@
|
|||
|
||||
contributor_guidelines
|
||||
|
||||
ci
|
||||
|
||||
cicd_setup
|
||||
|
||||
regression_tests
|
||||
|
|
|
|||
Loading…
Reference in New Issue