Introduced initial quick start

docs/source/index.rst

@@ -29,6 +29,7 @@ Efabless Caravel "harness" SoC
    irq
    sram
    programming
+   quick-start
    memory-mapped-io-summary
    supplementary-figures
    maximum-ratings

docs/source/introduction.rst

@@ -28,6 +28,7 @@ The documentation contains the following chapters:
 * :doc:`irq` describes the interrups,
 * :doc:`sram` describes management and storage area SRAM,
 * :doc:`programming` shows how to get started with programming on Caravel chip,
+* :doc:`quick-start` shows how to add custom user project to Caravel harness,
 * :doc:`memory-mapped-io-summary` lists the memory mapped I/O registers by address,
 * :doc:`supplementary-figures` provides supplementary internal structure and die arrangement figures 
 * :doc:`maximum-ratings` lists the parameters and their ranges at which the device operates correctly,

docs/source/quick-start.rst

@@ -0,0 +1,175 @@
+User project quick start guide
+==============================
+
+This section describes how to get going with the `efabless/caravel repository <https://github.com/efabless/caravel>`_ by adding a user project to the harness and merging the ``.gds`` files to create your own ``caravel.gds``.
+
+Building the example user project
+---------------------------------
+
+Building the example user project works without any configuration needed. Just cd into ``openlane`` and run ``make`` on the wanted targets:
+
+.. code-block:: bash
+
+   cd openlane
+   make user_proj_example
+   make user_project_wrapper
+
+Prerequisites
+-------------
+
+* OpenLANE
+* Caravel
+
+If you have followed the Getting Started Guide you should have all of these installed. To proceed make sure, that your environment variables are set correctly:
+
+.. code-block:: bash
+
+   export PDK_ROOT=/path/to/pdk
+   export OPENLANE_ROOT=/path/to/openlane
+
+Adding a user project
+---------------------
+
+Requirements
+^^^^^^^^^^^^
+
+In the current version of Caravel the top level module of your design needs to be compatible with the interface required by `user_project_wrapper <https://github.com/efabless/caravel/blob/develop/verilog/rtl/user_project_wrapper.v>`_. Make sure that your design uses the same ports as ``user_proj_example``.
+
+
+Adding a new design
+^^^^^^^^^^^^^^^^^^^
+
+To add a user project, there are multiple possible ways:
+
+* Creating a new design in ``openlane``
+* Modifying ``user_proj_example`` to incorporate your design
+* Replacing ``user_project_wrapper`` with your design
+
+In this guide we will focus on the first option, creating a new design. A design in Caravel/OpenLANE has the following structure:
+
+.. code-block:: bash
+
+   openlane/design_name
+   ├── config.tcl
+   └── pinout.cfg
+
+The configuration file ``config.tcl`` contains configuration options and parameters, as well as the path to the source files, which are not located inside the design folder, but rather at the top level of the repository in ``verilog/rtl``. The ``pinout.cfg`` contains the pin configuration, which you should copy from ``user_proj_example`` without modifying it.
+
+To create your own design go into ``openlane`` and create a new directory named like your design with the appropriate config file and copy ``pinout.cfg`` from ``user_proj_example``. The name of the directory  should be the same as the top level module of your design. You can also copy the config file from ``user_proj_example``, as it provides a good starting point for your own configuration.
+
+.. code-block:: bash
+
+   cd openlane
+   mkdir user_proj
+   cp user_proj_example/config.tcl user_proj/
+
+Configuration
+^^^^^^^^^^^^^
+
+Configuration options and their parameters can be found in the `OpenLANE repository <https://github.com/efabless/openlane/tree/master/configuration>`_.
+
+It is recommended to create a new subdirectory for your source files under ``verilog/rtl`` if you have more than one source file and place them there. Alternatively you can just place them in ``verilog/rtl``. After adding your source files you have to provide the path to them in your ``config.tcl``:
+
+.. code-block:: tcl
+
+   set ::env(VERILOG_FILES) "\
+	$script_dir/../../verilog/rtl/defines.v \
+	$script_dir/../../verilog/rtl/user_proj/top_level.v \
+	$script_dir/../../verilog/rtl/user_proj/ctrl.v \
+	$script_dir/../../verilog/rtl/user_proj/io.v"
+
+There are three more configuration options you have to adjust:
+
+* ``DESIGN_NAME``: This has to be equal to the name of your top level module and therefore your design directory.
+* ``CLOCK_PORT``: The clock port. If your design does not have one you can use ``wb_clk_i``
+* ``CLOCK_NET``: The clock net. This does not have to be set manually. To unset it just delete the line.
+
+Building your design
+--------------------
+
+To build your design go into ``openlane`` and run make with your design name as a target:
+
+.. code-block:: bash
+
+   cd openlane
+   make user_proj
+
+This will run your design throught the OpenLANE workflow and if successfull produce a ``.gds`` file of your project. The subdirectory ``runs/user_proj`` will be created in your designs folder, which contains the results of the run. The following result files in ``runs/user_proj/`` are important:
+
+* ``user_proj/runs/user_proj/reports/final_summary_report.csv``: Contains the results of the run including violations
+* ``user_proj/runs/user_proj/results/magic/user_proj.lef``
+* ``user_proj/runs/user_proj/results/magic/user_proj.gds``
+
+The ``.gds`` and ``.lef`` files can also be found in the ``gds`` and ``lef`` directories on the top level of the repository.
+
+Adding your design to the wrapper
+---------------------------------
+
+After building your design you can add it to ``user_project_wrapper``, which takes the ``.gds`` and ``.lef`` files you produced by building your design. To achieve this, we need to adjust a few configuration options in ``user_project_wrapper/config.tcl``:
+
+.. code-block:: tcl
+
+   set ::env(VERILOG_FILES_BLACKBOX) "\
+       $script_dir/../../verilog/rtl/defines.v \
+       $script_dir/../../verilog/rtl/user_proj/top_level.v"
+
+   set ::env(EXTRA_LEFS) "\
+       $script_dir/../../lef/user_proj.lef"
+
+   set ::env(EXTRA_GDS_FILES) "\
+       $script_dir/../../gds/user_proj.gds"
+
+In many cases it will be sufficient, to just replace ``user_proj_example`` with the name of your user project. For ``VERILOG_FILES_BLACKBOX`` you need to provide the path to the source file of your top level module.
+
+Placement macro
+^^^^^^^^^^^^^^^
+
+If your design is different in size to the example you should adjust the position, where your module will be placed inside the wrapper. This can be done in ``user_project_wrapper/interactive.tcl``:
+
+.. code-block:: tcl
+
+   add_macro_placement mprj 850 1100 N
+
+In this case 850/1100 specify the X/Y position of the macro. The size of the wrapper can be found in ``user_project_wrapper/config.tcl``, with that and the size of your design you can figure out, where you need to place your design.
+
+Building the wrapper
+^^^^^^^^^^^^^^^^^^^^
+
+After modifying the configuration files of the wrapper you can build it to produce a wrapper, which contains your design:
+
+.. code-block:: bash
+
+   cd openlane
+   make user_project_wrapper
+
+Building Caravel
+----------------
+
+To build the whole Caravel system you just need to run make in the root of the repository:
+
+.. code-block:: bash
+
+   make
+
+The resulting ``.gds`` file can be found in ``gds/caravel.gds``.
+
+Troubleshooting
+---------------
+
+Common error messages/warnings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Pin mprj/xxx is outside die area
+""""""""""""""""""""""""""""""""
+
+Either your design is too big for the wrapper or you need to adjust the position of your design in the wrapper. See `Placement macro <#placement-macro>`_.
+
+No clock nets have been found
+"""""""""""""""""""""""""""""
+
+``CLOCK_PORT`` in your config.tcl is not set propertly.
+
+Design congestion too high
+""""""""""""""""""""""""""
+
+Reduce ``PL_TARGET_DENSITY``.