mirror of
https://github.com/YosysHQ/yosys
synced 2025-06-24 14:53:42 +00:00
Docs: Merge yosys_source into extending_yosys
Move abc_flow content into synthesis/abc document.
This commit is contained in:
Krystine Sherwin
parent
8e618cac45
commit
00bb3b6fc2
6 changed files with 88 additions and 94 deletions
|
|
@ -1,76 +0,0 @@
|
|||
Setting up a flow for ABC9
|
||||
--------------------------
|
||||
|
||||
Much of the configuration comes from attributes and ``specify`` blocks in
|
||||
Verilog simulation models.
|
||||
|
||||
``specify`` syntax
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Since ``specify`` is a relatively obscure part of the Verilog standard, a quick
|
||||
guide to the syntax:
|
||||
|
||||
.. code-block:: verilog
|
||||
|
||||
specify // begins a specify block
|
||||
(A => B) = 123; // simple combinational path from A to B with a delay of 123.
|
||||
(A *> B) = 123; // simple combinational path from A to all bits of B with a delay of 123 for all.
|
||||
if (FOO) (A => B) = 123; // paths may apply under specific conditions.
|
||||
(posedge CLK => (Q : D)) = 123; // combinational path triggered on the positive edge of CLK; used for clock-to-Q arrival paths.
|
||||
$setup(A, posedge CLK, 123); // setup constraint for an input relative to a clock.
|
||||
endspecify // ends a specify block
|
||||
|
||||
By convention, all delays in ``specify`` blocks are in integer picoseconds.
|
||||
Files containing ``specify`` blocks should be read with the ``-specify`` option
|
||||
to :cmd:ref:`read_verilog` so that they aren't skipped.
|
||||
|
||||
LUTs
|
||||
^^^^
|
||||
|
||||
LUTs need to be annotated with an ``(* abc9_lut=N *)`` attribute, where ``N`` is
|
||||
the relative area of that LUT model. For example, if an architecture can combine
|
||||
LUTs to produce larger LUTs, then the combined LUTs would have increasingly
|
||||
larger ``N``. Conversely, if an architecture can split larger LUTs into smaller
|
||||
LUTs, then the smaller LUTs would have smaller ``N``.
|
||||
|
||||
LUTs are generally specified with simple combinational paths from the LUT inputs
|
||||
to the LUT output.
|
||||
|
||||
DFFs
|
||||
^^^^
|
||||
|
||||
DFFs should be annotated with an ``(* abc9_flop *)`` attribute, however ABC9 has
|
||||
some specific requirements for this to be valid: - the DFF must initialise to
|
||||
zero (consider using :cmd:ref:`dfflegalize` to ensure this). - the DFF cannot
|
||||
have any asynchronous resets/sets (see the simplification idiom and the Boxes
|
||||
section for what to do here).
|
||||
|
||||
It is worth noting that in pure ``abc9`` mode, only the setup and arrival times
|
||||
are passed to ABC9 (specifically, they are modelled as buffers with the given
|
||||
delay). In ``abc9 -dff``, the flop itself is passed to ABC9, permitting
|
||||
sequential optimisations.
|
||||
|
||||
Some vendors have universal DFF models which include async sets/resets even when
|
||||
they're unused. Therefore *the simplification idiom* exists to handle this: by
|
||||
using a ``techmap`` file to discover flops which have a constant driver to those
|
||||
asynchronous controls, they can be mapped into an intermediate, simplified flop
|
||||
which qualifies as an ``(* abc9_flop *)``, ran through :cmd:ref:`abc9`, and then
|
||||
mapped back to the original flop. This is used in :cmd:ref:`synth_intel_alm` and
|
||||
:cmd:ref:`synth_quicklogic` for the PolarPro3.
|
||||
|
||||
DFFs are usually specified to have setup constraints against the clock on the
|
||||
input signals, and an arrival time for the ``Q`` output.
|
||||
|
||||
Boxes
|
||||
^^^^^
|
||||
|
||||
A "box" is a purely-combinational piece of hard logic. If the logic is exposed
|
||||
to ABC9, it's a "whitebox", otherwise it's a "blackbox". Carry chains would be
|
||||
best implemented as whiteboxes, but a DSP would be best implemented as a
|
||||
blackbox (multipliers are too complex to easily work with). LUT RAMs can be
|
||||
implemented as whiteboxes too.
|
||||
|
||||
Boxes are arguably the biggest advantage that ABC9 has over ABC: by being aware
|
||||
of carry chains and DSPs, it avoids optimising for a path that isn't the actual
|
||||
critical path, while the generally-longer paths result in ABC9 being able to
|
||||
reduce design area by mapping other logic to larger-but-slower cells.
|
||||
128
docs/source/yosys_internals/extending_yosys/build_verific.rst
Normal file
128
docs/source/yosys_internals/extending_yosys/build_verific.rst
Normal file
|
|
@ -0,0 +1,128 @@
|
|||
Compiling with Verific library
|
||||
==============================
|
||||
|
||||
The easiest way to get Yosys with Verific support is to `contact YosysHQ`_ for a
|
||||
`Tabby CAD Suite`_ evaluation license and download link. The TabbyCAD Suite
|
||||
includes additional patches and a custom extensions library in order to get the
|
||||
most out of the Verific parser when using Yosys.
|
||||
|
||||
If you already have a license for the Verific parser, in either source or binary
|
||||
form, you may be able to compile Yosys with partial Verific support yourself.
|
||||
|
||||
.. _contact YosysHQ : https://www.yosyshq.com/contact
|
||||
.. _Tabby CAD Suite: https://www.yosyshq.com/tabby-cad-datasheet
|
||||
|
||||
The Yosys-Verific patch
|
||||
-----------------------
|
||||
|
||||
.. todo:: Fill out section on Yosys-Verific patch
|
||||
|
||||
* Yosys-Verific patch developed for best integration
|
||||
* Needed for some of the formal verification front-end tools
|
||||
* `contact YosysHQ`_ about licensing this patch for your own Yosys builds
|
||||
* Unable to provide support for builds without this patch
|
||||
|
||||
New cells
|
||||
~~~~~~~~~
|
||||
|
||||
============== ===========
|
||||
Cell Description
|
||||
============== ===========
|
||||
$initstate
|
||||
$set_tag
|
||||
$get_tag
|
||||
$overwrite_tag
|
||||
$original_tag
|
||||
$future_ff
|
||||
============== ===========
|
||||
|
||||
.. todo:: (sub)section on features only available with TabbyCAD
|
||||
|
||||
Compile options
|
||||
---------------
|
||||
|
||||
To enable Verific support ``ENABLE_VERIFIC`` has to be set to ``1`` and
|
||||
``VERIFIC_DIR`` needs to point to the location where the library is located.
|
||||
|
||||
============== ========================== ===============================
|
||||
Parameter Default Description
|
||||
============== ========================== ===============================
|
||||
ENABLE_VERIFIC 0 Enable compilation with Verific
|
||||
VERIFIC_DIR /usr/local/src/verific_lib Library and headers location
|
||||
============== ========================== ===============================
|
||||
|
||||
Since there are multiple Verific library builds and they can have different
|
||||
features, there are compile options to select them.
|
||||
|
||||
================================= ======= ===================================
|
||||
Parameter Default Description
|
||||
================================= ======= ===================================
|
||||
ENABLE_VERIFIC_SYSTEMVERILOG 1 SystemVerilog support
|
||||
ENABLE_VERIFIC_VHDL 1 VHDL support
|
||||
ENABLE_VERIFIC_HIER_TREE 1 Hierarchy tree support
|
||||
ENABLE_VERIFIC_YOSYSHQ_EXTENSIONS 1 YosysHQ specific extensions support
|
||||
ENABLE_VERIFIC_EDIF 0 EDIF support
|
||||
ENABLE_VERIFIC_LIBERTY 0 Liberty file support
|
||||
================================= ======= ===================================
|
||||
|
||||
Supported build
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
The default values for options represent the only fully supported configuration
|
||||
of Yosys with Verific. This build includes SystemVerilog and VHDL support with
|
||||
RTL elaboration, hierarchy tree and static elaboration for both languages. This
|
||||
is the only configuration for which the Yosys-Verific patch is available.
|
||||
|
||||
.. note::
|
||||
|
||||
TabbyCAD builds also have additional EDIF and Liberty file support enabled.
|
||||
YosysHQ extensions library is only part of TabbyCAD as a product.
|
||||
|
||||
.. todo:: is "YosysHQ extensions library" == "YosysHQ specific extensions support" ?
|
||||
|
||||
If not, they need to be better distinguished. If they are, then how is it
|
||||
possible for someone to build the supported configuration?
|
||||
|
||||
Partially supported builds
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To be able to compile Yosys with Verific, the Verific library must have support
|
||||
for at least one HDL language with RTL elaboration enabled. The following table
|
||||
lists a series of build configurations which are possible, but only provide a
|
||||
limited subset of features. Please note that support is limited without YosysHQ
|
||||
specific extensions of Verific library.
|
||||
|
||||
+--------------------------------------------------------------------------+---------------+------+-----------+--------------------+
|
||||
| | Configuration values beginning with ENABLE_VERIFIC\_ |
|
||||
+--------------------------------------------------------------------------+---------------+------+-----------+--------------------+
|
||||
| Features | SYSTEMVERILOG | VHDL | HIER_TREE | YOSYSHQ_EXTENSIONS |
|
||||
+==========================================================================+===============+======+===========+====================+
|
||||
| SystemVerilog + RTL elaboration | 1 | 0 | 0 | 0 |
|
||||
+--------------------------------------------------------------------------+---------------+------+-----------+--------------------+
|
||||
| VHDL + RTL elaboration | 0 | 1 | 0 | 0 |
|
||||
+--------------------------------------------------------------------------+---------------+------+-----------+--------------------+
|
||||
| SystemVerilog + VHDL + RTL elaboration | 1 | 1 | 0 | 0 |
|
||||
+--------------------------------------------------------------------------+---------------+------+-----------+--------------------+
|
||||
| SystemVerilog + RTL elaboration + Static elaboration + Hier tree | 1 | 0 | 1 | 0 |
|
||||
+--------------------------------------------------------------------------+---------------+------+-----------+--------------------+
|
||||
| VHDL + RTL elaboration + Static elaboration + Hier tree | 0 | 1 | 1 | 0 |
|
||||
+--------------------------------------------------------------------------+---------------+------+-----------+--------------------+
|
||||
| SystemVerilog + VHDL + RTL elaboration + Static elaboration + Hier tree | 1 | 1 | 1 | 0 |
|
||||
+--------------------------------------------------------------------------+---------------+------+-----------+--------------------+
|
||||
|
||||
.. note::
|
||||
|
||||
In case your Verific build has EDIF and/or Liberty support, you can enable
|
||||
those options. These are not mentioned above for simplification and since
|
||||
they are disabled by default.
|
||||
|
||||
Verific Features that should be enabled in your Verific library
|
||||
---------------------------------------------------------------
|
||||
|
||||
Please be aware that the following Verific configuration build parameter needs
|
||||
to be enabled in order to create the fully supported build.
|
||||
|
||||
::
|
||||
|
||||
database/DBCompileFlags.h:
|
||||
DB_PRESERVE_INITIAL_VALUE
|
||||
|
|
@ -1,11 +1,14 @@
|
|||
Extending Yosys
|
||||
---------------
|
||||
Working with the Yosys codebase
|
||||
-------------------------------
|
||||
|
||||
.. todo:: brief overview for the extending Yosys index
|
||||
This section goes into additional detail on the Yosys source code and git
|
||||
repository. This information is not needed for simply using Yosys, but may be
|
||||
of interest for developers looking to customise Yosys builds.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
extensions
|
||||
abc_flow
|
||||
build_verific
|
||||
test_suites
|
||||
|
||||
|
|
|
|||
25
docs/source/yosys_internals/extending_yosys/test_suites.rst
Normal file
25
docs/source/yosys_internals/extending_yosys/test_suites.rst
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
Testing Yosys
|
||||
=============
|
||||
|
||||
.. todo:: more about the included test suite
|
||||
|
||||
Automatic testing
|
||||
-----------------
|
||||
|
||||
.. only:: html
|
||||
|
||||
The `Yosys Git repo`_ has automatic testing of builds and running of the
|
||||
included test suite on the following platforms:
|
||||
|
||||
- Ubuntu |test-linux|
|
||||
- macOS |test-macos|
|
||||
|
||||
.. _Yosys Git repo: https://github.com/YosysHQ/yosys
|
||||
|
||||
.. |test-linux| image:: https://github.com/YosysHQ/yosys/actions/workflows/test-linux.yml/badge.svg?branch=main
|
||||
.. |test-macos| image:: https://github.com/YosysHQ/yosys/actions/workflows/test-macos.yml/badge.svg?branch=main
|
||||
|
||||
For up to date information, including OS versions, refer to `the git actions
|
||||
page`_.
|
||||
|
||||
.. _the git actions page: https://github.com/YosysHQ/yosys/actions
|
||||
Loading…
Add table
Add a link
Reference in a new issue