diff --git a/docs/source/appendix/auxlibs.rst b/docs/source/appendix/auxlibs.rst index a77eb8b3f..4c845f197 100644 --- a/docs/source/appendix/auxlibs.rst +++ b/docs/source/appendix/auxlibs.rst @@ -4,7 +4,7 @@ Auxiliary libraries The Yosys source distribution contains some auxiliary libraries that are compiled into Yosys and can be used in plugins. -.. todo:: fill out the newer auxiliary libs +.. TODO:: fill out the newer auxiliary libs BigInt ------ diff --git a/docs/source/appendix/auxprogs.rst b/docs/source/appendix/auxprogs.rst index 6b2d04d71..2235bbd89 100644 --- a/docs/source/appendix/auxprogs.rst +++ b/docs/source/appendix/auxprogs.rst @@ -19,7 +19,7 @@ Yosys. See :doc:`/yosys_internals/extensions` for details. yosys-filterlib --------------- -.. todo:: how does a filterlib rules-file work? is this still supported? +.. todo:: how does a filterlib rules-file work? The ``yosys-filterlib`` tool is a small utility that can be used to strip or extract information from a Liberty file. This can be useful for removing diff --git a/docs/source/getting_started/example_synth.rst b/docs/source/getting_started/example_synth.rst index c4da2dd8c..6dac3a9a9 100644 --- a/docs/source/getting_started/example_synth.rst +++ b/docs/source/getting_started/example_synth.rst @@ -23,8 +23,9 @@ A simple counter .. role:: yoscrypt(code) :language: yoscrypt -.. todo:: consider changing simple counter example for something with memory - using e.g. synth_ice40 to cover more of the synth flow +.. TODO:: move current example synth as mapping to cell libraries + + replace with a walk through of synth_ice40 This section covers an `example project`_ available in ``docs/source/code_examples/intro/``. The project contains a simple ASIC @@ -77,7 +78,7 @@ stopping the following commands from trying to work on them. By passing the that if the design includes any non-blackbox modules without an implementation it should return an error. -.. todo:: more on why :cmd:ref:`hierarchy` is important +.. TODO:: more on why :cmd:ref:`hierarchy` is important .. note:: @@ -147,7 +148,7 @@ Much better. We can now see that the ``$dff`` and ``$mux`` cells have been replaced with a single ``$sdffe``, using the built-in enable and reset ports instead. -.. todo:: a bit more on :cmd:ref:`opt` here +.. TODO:: a bit more on :cmd:ref:`opt` here At this stage of a synthesis flow there are a few other commands we could run. First off is :cmd:ref:`flatten`. If we had any modules within our ``counter``, @@ -176,7 +177,7 @@ Such elements have to be inferred from patterns in the design and there are special passes for each. Detection of these patterns can also be affected by optimizations and other transformations done previously. -.. todo:: talk more about DSPs (and their associated commands) +.. TODO:: talk more about DSPs (and their associated commands) Some of the commands we might use here are: @@ -194,7 +195,7 @@ Some of the commands we might use here are: Logic gate mapping ~~~~~~~~~~~~~~~~~~ -.. todo:: example_synth mapping to gates +.. TODO:: example_synth mapping to gates :yoscrypt:`techmap` - Map coarse-grain RTL cells (adders, etc.) to fine-grain logic gates (AND, OR, NOT, etc.). @@ -217,7 +218,7 @@ cells used. Mapping to hardware ~~~~~~~~~~~~~~~~~~~ -.. todo:: example_synth mapping to hardware +.. TODO:: example_synth mapping to hardware :ref:`cmos_lib` diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst index 2f89a71cd..a3c4a265b 100644 --- a/docs/source/getting_started/index.rst +++ b/docs/source/getting_started/index.rst @@ -1,6 +1,8 @@ Getting started with Yosys ========================== +.. todo:: brief overview for the getting started index + .. toctree:: :maxdepth: 3 diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst index f32cdf69d..66c5a3335 100644 --- a/docs/source/getting_started/installation.rst +++ b/docs/source/getting_started/installation.rst @@ -34,22 +34,24 @@ Targeted architectures The `OSS CAD Suite`_ releases `nightly builds`_ for the following architectures: -- linux-x64 |linux-x64| - - Most personal Linux based computers +.. only:: html -- darwin-x64 |darwin-x64| - - macOS 10.14 or later with Intel CPU + - linux-x64 |linux-x64| + - Most personal Linux based computers -- darwin-arm64 |darwin-arm64| - - macOS 11.00 or later with M1 CPU + - darwin-x64 |darwin-x64| + - macOS 10.14 or later with Intel CPU -- windows-x64 |windows-x64| - - Targeted for Windows 10 and 11, but older 64-bit version of Windows 7, 8, - or 8.1 should work + - darwin-arm64 |darwin-arm64| + - macOS 11.00 or later with M1 CPU -- linux-arm |linux-arm| -- linux-arm64 |linux-arm64| -- linux-riscv64 (untested) |linux-riscv64| + - windows-x64 |windows-x64| + - Targeted for Windows 10 and 11, but older 64-bit version of Windows 7, + 8, or 8.1 should work + + - linux-arm |linux-arm| + - linux-arm64 |linux-arm64| + - linux-riscv64 (untested) |linux-riscv64| .. _OSS CAD Suite: https://github.com/YosysHQ/oss-cad-suite-build .. _nightly builds: https://github.com/YosysHQ/oss-cad-suite-build/releases/latest @@ -141,7 +143,7 @@ executable name). Source tree and build system ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. todo:: check if source tree/build system details need updating +.. TODO:: check if source tree/build system details need updating The Yosys source tree is organized into the following top-level directories: diff --git a/docs/source/getting_started/scripting_intro.rst b/docs/source/getting_started/scripting_intro.rst index fd2aeee88..d065a6485 100644 --- a/docs/source/getting_started/scripting_intro.rst +++ b/docs/source/getting_started/scripting_intro.rst @@ -1,7 +1,7 @@ Scripting in Yosys ------------------ -.. todo:: check logical consistency +.. TODO:: logical consistency, esp with example_synth Yosys reads and processes commands from synthesis scripts, command line arguments and an interactive command prompt. Yosys commands consist of a command diff --git a/docs/source/index.rst b/docs/source/index.rst index 17e12f123..bbefa521f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,16 +2,30 @@ Yosys Open SYnthesis Suite ================================================================================ -.. todo:: better landing page - - Consider adding something here that isn't just table of contents since this - *is* the root page and is where the logo links to. +Yosys is an open source framework for RTL synthesis. To learn more about Yosys, +see :doc:`/introduction`. For a quick guide on how to get started using Yosys, +check out :doc:`/getting_started/index`. For the complete list of commands +available, go to :ref:`commandindex`. + +.. note:: + + This documentation recently went through a major restructure. If you're + looking for something from the previous version and can't find it here, + please `let us know`_. Documentation from before the restructure can still + be found by switching to `version 0.36`_ or earlier. Note that the previous + theme does not include a version switcher. + +.. _let us know: https://github.com/YosysHQ/yosys/issues/new/choose +.. _version 0.36: https://yosyshq.readthedocs.io/projects/yosys/en/0.36/ .. todo:: look into command ref improvements - Search bar with live drop down suggestions for matching on title / autocompleting commands - Scroll the left sidebar to the current location on page load + - Also the formatting/linking in pdf is broken + +.. todolist:: .. only:: html @@ -28,16 +42,3 @@ Yosys Open SYnthesis Suite test_suites appendix - -.. only:: html - - Indices - ------- - - - :ref:`commandindex` - - :ref:`tagindex` - -TODOs ------ - -.. todolist:: diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index b4934ad78..292c6ceec 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -7,8 +7,8 @@ more general infrastructure for research on synthesis. Modern Yosys has full support for the synthesizable subset of Verilog-2005 and has been described as "the GCC of hardware synthesis." Freely available and -`open source`_, Yosys finds use across hobbyist and commercial applications as well -as academic. +`open source`_, Yosys finds use across hobbyist and commercial applications as +well as academic. .. _open source: https://github.com/YosysHQ/yosys @@ -71,8 +71,15 @@ Things you can't do .. _nextpnr: https://github.com/YosysHQ/nextpnr -The extended Yosys universe ---------------------------- +The Yosys family +---------------- + +As mentioned above, `YosysHQ`_ maintains not just Yosys but an entire family of +tools built around it. + +.. _YosysHQ: https://github.com/YosysHQ + +.. TODO:: Yosys family descriptions In no particular order: diff --git a/docs/source/test_suites.rst b/docs/source/test_suites.rst index 3fa84ad3e..b37263144 100644 --- a/docs/source/test_suites.rst +++ b/docs/source/test_suites.rst @@ -9,8 +9,10 @@ Automatic testing The `Yosys Git repo`_ has automatic testing of builds and running of the included test suite on the following platforms: -- Ubuntu 20.04 (Focal Fossa) |test-linux| -- macOS 11 (Big Sur) |test-macos| +.. only:: html + + - Ubuntu 20.04 (Focal Fossa) |test-linux| + - macOS 11 (Big Sur) |test-macos| .. _Yosys Git repo: https://github.com/YosysHQ/yosys diff --git a/docs/source/using_yosys/index.rst b/docs/source/using_yosys/index.rst index d254df76f..91d34bfe4 100644 --- a/docs/source/using_yosys/index.rst +++ b/docs/source/using_yosys/index.rst @@ -1,6 +1,8 @@ Using Yosys (advanced) ====================== +.. todo:: brief overview for the using Yosys index + .. toctree:: :maxdepth: 2 diff --git a/docs/source/using_yosys/more_scripting/index.rst b/docs/source/using_yosys/more_scripting/index.rst index 976de0cbd..7c3f2ae56 100644 --- a/docs/source/using_yosys/more_scripting/index.rst +++ b/docs/source/using_yosys/more_scripting/index.rst @@ -1,6 +1,8 @@ More scripting -------------- +.. todo:: brief overview for the more scripting index + .. toctree:: :maxdepth: 3 diff --git a/docs/source/using_yosys/more_scripting/interactive_investigation.rst b/docs/source/using_yosys/more_scripting/interactive_investigation.rst index 08d41702d..baa4b7e03 100644 --- a/docs/source/using_yosys/more_scripting/interactive_investigation.rst +++ b/docs/source/using_yosys/more_scripting/interactive_investigation.rst @@ -260,7 +260,7 @@ switch back). Now the `ls` command lists the objects within that module. :numref:`lscd` below demonstrates this using the ``example.v`` from `A simple circuit`_ -.. todo:: update yosys output with $ternary$example.v$3 +.. TODO:: update yosys output with $ternary$example.v$3 .. code-block:: none :caption: Demonstration of :cmd:ref:`ls` and :cmd:ref:`cd` having run ``yosys example.v`` diff --git a/docs/source/using_yosys/more_scripting/selections.rst b/docs/source/using_yosys/more_scripting/selections.rst index 6504bc0bb..0db716ccc 100644 --- a/docs/source/using_yosys/more_scripting/selections.rst +++ b/docs/source/using_yosys/more_scripting/selections.rst @@ -263,7 +263,7 @@ diagram in :numref:`memdemo_00`. Complete circuit diagram for the design shown in :numref:`memdemo_src` -.. todo:: :ref:`memdemo_01` and :ref:`memdemo_02` are the same, probably change +.. TODO:: :ref:`memdemo_01` and :ref:`memdemo_02` are the same, probably change the example so they aren't. There's a lot going on there, but maybe we are only interested in the tree of diff --git a/docs/source/using_yosys/synthesis/abc.rst b/docs/source/using_yosys/synthesis/abc.rst index a46072fee..e703b8986 100644 --- a/docs/source/using_yosys/synthesis/abc.rst +++ b/docs/source/using_yosys/synthesis/abc.rst @@ -1,7 +1,7 @@ The :cmd:ref:`abc` command ~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. todo:: discuss abc (more stable) vs abc9 (newer, possibly better) +.. TODO:: discuss abc, consider using https://github.com/Ravenslofty/yosys-cookbook/blob/master/misc/abc9.md The :cmd:ref:`abc` command provides an interface to ABC_, an open source tool for low-level logic synthesis. diff --git a/docs/source/using_yosys/synthesis/index.rst b/docs/source/using_yosys/synthesis/index.rst index 007fd555d..d062c1c3d 100644 --- a/docs/source/using_yosys/synthesis/index.rst +++ b/docs/source/using_yosys/synthesis/index.rst @@ -1,6 +1,8 @@ Synthesis in detail ------------------- +.. todo:: brief overview for the synthesis index + .. toctree:: :maxdepth: 3 diff --git a/docs/source/using_yosys/synthesis/memory.rst b/docs/source/using_yosys/synthesis/memory.rst index 721a86672..499f73d5a 100644 --- a/docs/source/using_yosys/synthesis/memory.rst +++ b/docs/source/using_yosys/synthesis/memory.rst @@ -57,7 +57,7 @@ Example Memory mapping ^^^^^^^^^^^^^^ -.. todo:: :cmd:ref:`memory_libmap` description +.. TODO:: :cmd:ref:`memory_libmap` description Usually it is preferred to use architecture-specific RAM resources for memory. For example: diff --git a/docs/source/using_yosys/synthesis/opt.rst b/docs/source/using_yosys/synthesis/opt.rst index 7851e78be..407308a29 100644 --- a/docs/source/using_yosys/synthesis/opt.rst +++ b/docs/source/using_yosys/synthesis/opt.rst @@ -66,8 +66,6 @@ In some cases this pass can also optimize cells with some constant inputs. 1 :math:`b` :math:`b` ========= ========= =========== -.. todo:: How to format table? - :numref:`Table %s ` shows the replacement rules used for optimizing an ``$_AND_`` gate. The first three rules implement the obvious const folding rules. Note that 'any' might include dynamic values calculated by other @@ -131,7 +129,7 @@ is produced. The ``opt_rmdff`` pass ~~~~~~~~~~~~~~~~~~~~~~ -.. todo:: Update to ``opt_dff`` +.. TODO:: Update to ``opt_dff`` This pass identifies single-bit d-type flip-flops (``$_DFF_``, ``$dff``, and ``$adff`` cells) with a constant data input and replaces them with a constant diff --git a/docs/source/using_yosys/synthesis/synth.rst b/docs/source/using_yosys/synthesis/synth.rst index 62cac991b..c9ec45b8a 100644 --- a/docs/source/using_yosys/synthesis/synth.rst +++ b/docs/source/using_yosys/synthesis/synth.rst @@ -4,11 +4,10 @@ Synth commands Packaged ``synth_*`` commands ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. todo:: are all these synth commands supported? - The following is a list of all synth commands included in Yosys for different platforms. Each command runs a script of sub commands specific to the platform -being targeted. +being targeted. Note that not all of these scripts are actively maintained and +may not be up-to-date. - :doc:`/cmd/synth_achronix` - :doc:`/cmd/synth_anlogic` @@ -21,8 +20,8 @@ being targeted. - :doc:`/cmd/synth_gowin` - :doc:`/cmd/synth_greenpak4` - :doc:`/cmd/synth_ice40` -- :doc:`/cmd/synth_intel` -- :doc:`/cmd/synth_intel_alm` +- :doc:`/cmd/synth_intel` (MAX10, Cyclone IV) +- :doc:`/cmd/synth_intel_alm` (Cyclone V, Arria V, Cyclone 10 GX) - :doc:`/cmd/synth_lattice` - :doc:`/cmd/synth_nexus` - :doc:`/cmd/synth_quicklogic` diff --git a/docs/source/using_yosys/yosys_flows.rst b/docs/source/using_yosys/yosys_flows.rst index a3fae32a4..bafdb4c08 100644 --- a/docs/source/using_yosys/yosys_flows.rst +++ b/docs/source/using_yosys/yosys_flows.rst @@ -4,7 +4,7 @@ Flows, command types, and order Command order ------------- -.. todo:: check text is coherent +.. TODO:: check text is coherent Intro to coarse-grain synthesis ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/yosys_internals/formats/rtlil_rep.rst b/docs/source/yosys_internals/formats/rtlil_rep.rst index aefa11496..ce373ce6c 100644 --- a/docs/source/yosys_internals/formats/rtlil_rep.rst +++ b/docs/source/yosys_internals/formats/rtlil_rep.rst @@ -74,7 +74,7 @@ This has three advantages: - First, it is impossible that an auto-generated identifier collides with an identifier that was provided by the user. -.. todo:: ``opt_clean`` (or clean), also ``-purge`` +.. TODO:: ``opt_clean`` (or clean), also ``-purge`` - Second, the information about which identifiers were originally provided by the user is always available which can help guide some optimizations. For