Merge pull request #2852 from antmicro/umarcor/docs/update

docs: update

docs/development/getting-started.rst

@@ -0,0 +1,144 @@
+.. _Development:GettingStarted:
+
+Getting Started with F4PGA Toolchain development
+################################################
+
+.. IMPORTANT::
+   This documentation explains the first steps in the development of the toolchain itself: generating definitions about
+   the primitives and routing infrastructure of the architectures.
+   If you are looking for the **user documentation**, i.e. how to generate bitstreams from HDL designs, please look at
+   :doc:`f4pga:index` and :doc:`examples:index` instead.
+
+.. WARNING::
+  Generating Architecture Definition files is expected to take a long time to build, even on fast machines.
+  To run the tests in this repository, please make sure these resources are available:
+
+  * Memory: 5.5G
+  * Disk space: 20G
+
+
+This section provides an introduction on how to get started with the development of the F4PGA toolchain.
+Each FPGA architecture has its own toolchain backend that will be called during build.
+The aim of this repository is to gather the knowledge from those backends and generate useful human and machine readable
+documentation to be used by tools such as yosys, vpr and/or vpr.
+See `Project X-Ray <https://prjxray.readthedocs.io/en/latest/>`_
+and `Project Trellis <https://prjtrellis.readthedocs.io/en/latest/>`_ for more information.
+
+In order to generate architecture definitions, any intermediate file format or bitstreams, you can use one of the
+toolchain tests in this repository.
+The following steps describe the whole process:
+
+
+Prepare the environment
+=======================
+
+Clone the repository:
+
+.. sourcecode:: bash
+
+    git clone https://github.com/chipsalliance/f4pga-arch-defs.git
+
+Bootstrap an isolated Conda environment with all the necessary dependencies:
+
+.. sourcecode:: bash
+
+    cd f4pga-arch-defs
+    make env
+
+.. HINT::
+  This also checks out all the submodules and generates the build system (``Make`` or ``Ninja``) from the CMake
+  configuration.
+  If you want to use the ``Ninja`` build tool add this line before calling ``make env``:
+
+  .. sourcecode:: bash
+
+      export CMAKE_FLAGS="-GNinja"
+
+
+Build the tests
+===============
+
+While different architectures provide different build targets, there are some targets that should exist for all
+architectures.
+
+For development purposes a set of test designs are included for each supported architecture.
+In order to perform a build of a test design with the ``Make`` build system, enter the appropriate test build directory
+specific to your target architecture and invoke the desired target.
+
+Assuming that you would like to generate the bitstream ``.bit`` file with the counter example for the Arty board, which
+uses Xilinx Artix-7 FPGA, you will execute the following:
+
+.. sourcecode:: bash
+
+  cd build/xilinx/xc7/tests/counter
+  make counter_arty_bit
+
+If you use ``Ninja``, the target is accessible from the root of the build directory:
+
+.. sourcecode:: bash
+
+  cd build
+  ninja counter_arty_bit
+
+.. NOTE::
+ Test design target names are based on the following naming convention: ``<design>_<platform>_<target_step>``,
+ where ``<target_step>`` is the actual step to be done, e.g.: ``bit``, ``place``, ``route``, ``prog``.
+
+There are targets to run multiple tests at once:
+
+.. sourcecode:: bash
+
+  # Build all demo bitstreams, targetting all architectures
+  make all_demos
+
+  # Build all Xilinx 7-series demo bitstreams
+  make all_xc7
+
+  # Build all Lattice ICE40 demo bitstreams
+  make all_ice40
+
+  # Build all QuickLogic demo bitstreams
+  make all_quicklogic
+
+Specific bitstreams can be built by specifying their target name, followed by a suffix specifying the desired output.
+For example, the LUT-RAM test for the RAM64X1D primative is called `dram_test_64x1d`.
+Example targets are:
+
+.. sourcecode:: bash
+
+  # Just run synthesis on the input Verilog
+  make dram_test_64x1d_eblif
+
+  # Complete synthesis and place and route the circuit
+  make dram_test_64x1d_route
+
+  # Create the output bitstream (including synthesis and place and route)
+  make dram_test_64x1d_bin
+
+  # Run bitstream back into Vivado for timing checks, etc.
+  make dram_test_64x1d_vivado
+
+
+Load the bitstreams
+===================
+
+The last step to test the whole flow is to load the bitstream to your platform.
+The final output file can be found in the appropriate test directory, i.e:
+``build/xilinx/xc7/tests/counter/counter_arty/artix7-xc7a50t-arty-swbut-roi-virt-xc7a50t-arty-swbut-test/top.bit``
+
+Programming tools used in F4PGA are either provided as a conda package during the environment setup, or are automatically
+downloaded and referenced by ``CMake``.
+
+For convenience, the ``prog`` targets are provided for loading the bitstream, e.g.:
+
+.. sourcecode:: bash
+
+    make counter_arty_prog
+
+or for ``Ninja``:
+
+.. sourcecode:: bash
+
+    ninja counter_arty_prog
+
+Find further details about loading bitstreams in :ref:`f4pga:GettingStarted:LoadingBitstreams`.

docs/index.rst

@@ -41,13 +41,14 @@ Contents
 .. toctree::
    :maxdepth: 2
 
-   getting-started
-   README
+   tools
+   packages
 
 .. toctree::
    :maxdepth: 2
    :caption: Development
 
+   development/getting-started
    development/cmake
    development/structure
    development/notes