docs/source/quickstart.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
   -->
   
Quick start for caravel_user_project
====================================

------------
Dependencies
------------

- Docker: `Linux <https://hub.docker.com/search?q=&type=edition&offering=community&operating_system=linux&utm_source=docker&utm_medium=webreferral&utm_campaign=dd-smartbutton&utm_location=header>`_ ||  `Windows <https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=dd-smartbutton&utm_location=header>`_ || `Mac with Intel Chip <https://desktop.docker.com/mac/main/amd64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=dd-smartbutton&utm_location=header>`_ || `Mac with M1 Chip <https://desktop.docker.com/mac/main/arm64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=dd-smartbutton&utm_location=header>`_

===============================================================================================================================================================

---------------------
Starting your project
---------------------


#. To start the project you need to first create an empty Git project on Github and make sure your repo is public and includes a README

#. Open your Terminal. Create an empty folder to use as your Caravel workspace, and navigate to it.

	.. code:: bash

		# Create a directory and call it anything you want
		mkdir -p caravel_tutorial

		# navigate into the directory
		cd caravel_tutorial
	
#. Clone caravel_user_project and setup the git environment as follows

	.. code:: bash

		# Make sure that "caravel_example" matches the empty github repo name in step 1
		git clone -b mpw-5b https://github.com/efabless/caravel_user_project caravel_example
		cd caravel_example
		git remote rename origin upstream

		# You need to put your empty github repo URL from step 1
		git remote add origin <your github repo URL>

		# Create a new branch, you can name it anything 
		git checkout -b <my_branch>
		git push -u origin <my_branch>
	
#. Now that your git environment is setup, it's time to setup your local environment.

	* This command will setup your environment by installing the following 
		- caravel_lite (a lite version of caravel)
		- management core for simulation
		- openlane to harden your design 
		- pdk

	.. code:: bash

		make setup
	
#. Now you can start hardening your design

	* To start hardening you project you need 
		- RTL verilog model for your design for OpenLane to harden
		- A subdirectory for each macro in your project under ``openlane/`` directory, each subdirectory should include openlane configuration files for the macro

	.. code:: bash

		make <module_name>	
	..

		For an example of hardening a project please refer to `user_project_example <https://github.com/efabless/caravel_user_project/blob/dv-documentation-update/docs/source/index.rst#running-openlane>`_
	
#. Integrate modules into the user_project_wrapper

	- Change the environment variables ``VERILOG_FILES_BLACKBOX``, ``EXTRA_LEFS`` and ``EXTRA_GDS_FILES`` in ``openlane/user_project_wrapper/config.tcl`` to point to your module

	- Instantiate your module(s) in ``verilog/rtl/user_project_wrapper.v``

	- Harden the user_project_wrapper including your module(s), using this command

	.. code:: bash

		make user_project_wrapper

#. Run simulation on your design

	* You need to include your rtl/gl/gl+sdf files in ``verilog/includes/includes.<rtl/gl/gl+sdf>.caravel_user_project``

	**NOTE:** You shouldn't include the files inside the verilog code
	
	.. code:: bash

		make simenv

		# you can then run RTL simulations using
		make verify-<testbench-name>-rtl

		# OR GL simulation using
		make verify-<testbench-name>-gl

		# for example
		make verify-io_ports-rtl
	
#. Run the precheck locally 

	.. code:: bash

		make precheck
		make run-precheck
	
#. You are done! now go to www.efabless.com to submit your project!
   
   
.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
   :target: https://opensource.org/licenses/Apache-2.0
.. |User CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg
   :target: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml
.. |Caravel Build| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg
   :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml