docs/source/getting-started.rst

.. raw:: html

   <!---
   # SPDX-FileCopyrightText: 2020 Efabless Corporation
   #
   # Licensed under the Apache License, Version 2.0 (the "License");
   # you may not use this file except in compliance with the License.
   # You may obtain a copy of the License at
   #
   #      http://www.apache.org/licenses/LICENSE-2.0
   #
   # Unless required by applicable law or agreed to in writing, software
   # distributed under the License is distributed on an "AS IS" BASIS,
   # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   # See the License for the specific language governing permissions and
   # limitations under the License.
   #
   # SPDX-License-Identifier: Apache-2.0
   -->
.. _getting-started:

Getting Started
===============

-  For information on tooling and versioning, please refer to :doc:`tool-versioning`.

Start by cloning the repo and uncompressing the files.

.. code:: bash

    git clone https://github.com/efabless/caravel.git
    cd caravel
    make uncompress

Then you need to install the open\_pdks prerequisite:

-  `Magic VLSI Layout
   Tool <http://opencircuitdesign.com/magic/index.html>`__ is needed to
   run open\_pdks -- version >= 8.3.60\*

   .. note::

      You can avoid the need for the magic prerequisite by using
      the openlane docker to do the installation step in open\_pdks. This
      could be done by cloning
      `openlane <https://github.com/efabless/openlane/tree/master>`__ and
      following the instructions given there to use the Makefile.

Install the required version of the PDK by running the following
commands:

.. code:: bash

    export PDK_ROOT=<The place where you want to install the pdk>
    make pdk

Then, you can learn more about the caravel chip by watching these video:

-  Caravel User Project Features -- https://youtu.be/zJhnmilXGPo
-  Aboard Caravel -- How to put your design on Caravel? --
   https://youtu.be/9QV8SDelURk
-  Things to Clarify About Caravel -- What versions to use with Caravel?
   -- https://youtu.be/-LZ522mxXMw

   -  You could only use openlane:rc6
   -  Make sure you have the commit hashes provided here inside the
      `Makefile <https://github.com/efabless/caravel/blob/master/Makefile>`__

Aboard Caravel
--------------

Your area is the full user\_project\_wrapper, so feel free to add your
project there or create a differnt macro and harden it seperately then
insert it into the user\_project\_wrapper. For example, if your design
is analog or you're using a different tool other than OpenLANE.

If you will use OpenLANE to harden your design, go through the
instructions in this `README <https://github.com/efabless/caravel/blob/develop/openlane/README.rst>`__.

You must copy your synthesized gate-level-netlist for
``user_project_wrapper`` to ``verilog/gl/`` and overwrite
``user_project_wrapper.v``. Otherwise, you can point to it in
`info.yaml <https://github.com/efabless/caravel/blob/master/info.yaml>`__.

.. note::

    If you're using openlane to harden your design, this should
    happen automatically.

Then, you will need to put your design aboard the Caravel chip. Make
sure you have the following:

-  `Magic VLSI Layout
   Tool <http://opencircuitdesign.com/magic/index.html>`__ installed on
   your machine. We may provide a Dockerized version later.\*
-  You have your user\_project\_wrapper.gds under ``./gds/`` in the
   Caravel directory.

.. note::

    You can avoid the need for the magic prerequisite by
    using the openlane docker to run the make step. This
    `section <#running-make-using-openlane-magic>`__ shows how.

Run the following command:

.. code:: bash

    export PDK_ROOT=<The place where the installed pdk resides. The same PDK_ROOT used in the pdk installation step>
    make

|Expectation_DRC|

Running Make using OpenLANE Magic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To use the magic installed inside Openlane to complete the final GDS
streaming out step, export the following:

.. code:: bash

    export PDK_ROOT=<The location where the pdk is installed>
    export OPENLANE_ROOT=<the absolute path to the openlane directory cloned or to be cloned>
    export IMAGE_NAME=<the openlane image name installed on your machine. Preferably openlane:rc6>
    export CARAVEL_PATH=$(pwd)

Then, mount the docker:

.. code:: bash

    docker run -it -v $CARAVEL_PATH:$CARAVEL_PATH -v $OPENLANE_ROOT:/openLANE_flow -v $PDK_ROOT:$PDK_ROOT -e CARAVEL_PATH=$CARAVEL_PATH -e PDK_ROOT=$PDK_ROOT -u $(id -u $USER):$(id -g $USER) $IMAGE_NAME

Finally, once inside the docker run the following commands:

.. code:: bash

    cd $CARAVEL_PATH
    make
    exit

|Expectation_DRC|

IMPORTANT
^^^^^^^^^

Please make sure to run ``make compress`` before commiting anything to
your repository. Avoid having 2 versions of the
gds/user\_project\_wrapper.gds or gds/caravel.gds one compressed and the
other not compressed.

Required Directory Structure
----------------------------

-  ./gds/ : includes all the gds files used or produced from the
   project.
-  ./def/ : includes all the def files used or produced from the
   project.
-  ./lef/ : includes all the lef files used or produced from the
   project.
-  ./mag/ : includes all the mag files used or produced from the
   project.
-  ./maglef/ : includes all the maglef files used or produced from the
   project.
-  ./spi/lvs/ : includes all the maglef files used or produced from the
   project.
-  ./verilog/dv/ : includes all the simulation test benches and how to
   run them.
-  ./verilog/gl/ : includes all the synthesized/elaborated netlists.
-  ./verilog/rtl/ : includes all the Verilog RTLs and source files.
-  ./openlane/\ ``<macro>``/ : includes all configuration files used to
   run openlane on your project.
-  info.yaml: includes all the info required in `this
   example <https://github.com/efabless/caravel/blob/master/info.yaml>`__. Please make sure that you are pointing to an
   elaborated caravel netlist as well as a synthesized
   gate-level-netlist for the user\_project\_wrapper

Managment SoC
-------------

The managment SoC runs firmware that can be used to:

-  Configure User Project I/O pads
-  Observe and control User Project signals (through on-chip logic
   analyzer probes)
-  Control the User Project power supply

The memory map of the management SoC can be found
`here <https://github.com/efabless/caravel/blob/master/verilog/rtl/README>`__

User Project Area
-----------------

This is the user space. It has limited silicon area (TBD, about 3.1mm x 3.8mm) as well as a fixed number of I/O pads (37) and power pads (10).

See `the Caravel premliminary datasheet` https://caravel-harness.readthedocs.io/en/develop/ for details.

The repository contains a `sample user project <https://github.com/efabless/caravel/blob/master/verilog/rtl/user_proj_example.v>`__ that contains a binary 32-bit up counter.

.. raw:: html

   <p align="center">
   <img src="./_static/counter_32.png" width="50%" height="50%">
   </p>

The firmware running on the Management Area SoC, configures the I/O pads
used by the counter and uses the logic probes to observe/control the
counter. Three firmware examples are provided:

#. Configure the User Project I/O pads as o/p. Observe the counter value
   in the testbench: `IO\_Ports
   Test <https://github.com/efabless/caravel/blob/master/verilog/dv/caravel/user_proj_example/io_ports>`__.
#. Configure the User Project I/O pads as o/p. Use the Chip LA to load
   the counter and observe the o/p till it reaches 500:
   `LA\_Test1 <https://github.com/efabless/caravel/blob/master/verilog/dv/caravel/user_proj_example/la_test1>`__.
#. Configure the User Project I/O pads as o/p. Use the Chip LA to
   control the clock source and reset signals and observe the counter
   value for five clock cylcles:
   `LA\_Test2 <https://github.com/efabless/caravel/blob/master/verilog/dv/caravel/user_proj_example/la_test2>`__.

.. |Expectation_DRC| replace:: This should merge the GDSes using magic and you'll end up with your version of ``./gds/caravel.gds``. You should expect ^40 magic DRC violations with the current "development" state of caravel.