blob: 38351082bdf16aba68b6c6608ab3e56db6ea6bd9 [file] [log] [blame]
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -08001.. raw:: html
2
3 <!---
4 # SPDX-FileCopyrightText: 2020 Efabless Corporation
5 #
6 # Licensed under the Apache License, Version 2.0 (the "License");
7 # you may not use this file except in compliance with the License.
8 # You may obtain a copy of the License at
9 #
10 # http://www.apache.org/licenses/LICENSE-2.0
11 #
12 # Unless required by applicable law or agreed to in writing, software
13 # distributed under the License is distributed on an "AS IS" BASIS,
14 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 # See the License for the specific language governing permissions and
16 # limitations under the License.
17 #
18 # SPDX-License-Identifier: Apache-2.0
19 -->
20
Marwan Abbas3f390102022-02-21 11:59:43 +020021Quick start for caravel_user_project
22====================================
Marwan Abbas54c22d52022-02-22 12:27:50 +020023
Marwan Abbas90262c42022-02-22 12:34:29 +020024------------
25Dependencies
26------------
27
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020028- 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>`_
Marwan Abbas90262c42022-02-22 12:34:29 +020029
30===============================================================================================================================================================
31
32---------------------
33Starting your project
34---------------------
35
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080036
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020037#. 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
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080038
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020039#. Open your Terminal. Create an empty folder to use as your Caravel workspace, and navigate to it.
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080040
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020041 .. code:: bash
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080042
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020043 # Create a directory and call it anything you want
44 mkdir -p caravel_tutorial
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080045
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020046 # navigate into the directory
47 cd caravel_tutorial
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080048
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020049#. Clone caravel_user_project and setup the git environment as follows
50
51 .. code:: bash
52
53 # Make sure that "caravel_example" matches the empty github repo name in step 1
54 git clone -b mpw-5b https://github.com/efabless/caravel_user_project caravel_example
55 cd caravel_example
56 git remote rename origin upstream
57
58 # You need to put your empty github repo URL from step 1
59 git remote add origin <your github repo URL>
60
61 # Create a new branch, you can name it anything
62 git checkout -b <my_branch>
63 git push -u origin <my_branch>
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080064
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020065#. Now that your git environment is setup, it's time to setup your local environment.
Marwan Abbasfdff8582022-02-22 17:05:31 +020066
Marwan Abbasa70e7002022-02-23 16:12:46 +020067 * This command will setup your environment by installing the following
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020068 - caravel_lite (a lite version of caravel)
69 - management core for simulation
70 - openlane to harden your design
71 - pdk
Marwan Abbasfdff8582022-02-22 17:05:31 +020072
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020073 .. code:: bash
74
75 make setup
Marwan Abbasfdff8582022-02-22 17:05:31 +020076
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020077#. Now you can start hardening your design
Marwan Abbasfdff8582022-02-22 17:05:31 +020078
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020079 * To start hardening you project you need
80 - RTL verilog model for your design for OpenLane to harden
Marwan Abbasa70e7002022-02-23 16:12:46 +020081 - A subdirectory for each macro in your project under ``openlane/`` directory, each subdirectory should include openlane configuration files for the macro
Marwan Abbasfdff8582022-02-22 17:05:31 +020082
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020083 .. code:: bash
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080084
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020085 make <module_name>
86 ..
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080087
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020088 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>`_
Marwan Abbasfdff8582022-02-22 17:05:31 +020089
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020090#. Integrate modules into the user_project_wrapper
Marwan Abbasfdff8582022-02-22 17:05:31 +020091
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020092 - 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
Marwan Abbasfdff8582022-02-22 17:05:31 +020093
Marwan Abbasa70e7002022-02-23 16:12:46 +020094 - Instantiate your module(s) in ``verilog/rtl/user_project_wrapper.v``
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080095
Marwan Abbasa70e7002022-02-23 16:12:46 +020096 - Harden the user_project_wrapper including your module(s), using this command
Marwan Abbasfdff8582022-02-22 17:05:31 +020097
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020098 .. code:: bash
Marwan Abbasfdff8582022-02-22 17:05:31 +020099
Marwan Abbas7ccab9c2022-02-23 14:30:41 +0200100 make user_project_wrapper
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800101
Marwan Abbas7ccab9c2022-02-23 14:30:41 +0200102#. Run simulation on your design
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800103
Marwan Abbasa70e7002022-02-23 16:12:46 +0200104 * You need to include your rtl/gl/gl+sdf files in ``verilog/includes/includes.<rtl/gl/gl+sdf>.caravel_user_project``
Marwan Abbas7ccab9c2022-02-23 14:30:41 +0200105
106 **NOTE:** You shouldn't include the files inside the verilog code
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800107
Marwan Abbas7ccab9c2022-02-23 14:30:41 +0200108 .. code:: bash
109
110 make simenv
111
112 # you can then run RTL simulations using
113 make verify-<testbench-name>-rtl
114
115 # OR GL simulation using
116 make verify-<testbench-name>-gl
117
118 # for example
119 make verify-io_ports-rtl
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800120
Marwan Abbas7ccab9c2022-02-23 14:30:41 +0200121#. Run the precheck locally
122
123 .. code:: bash
124
125 make precheck
126 make run-precheck
127
128#. You are done! now go to www.efabless.com to submit your project!
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800129
130
131.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
132 :target: https://opensource.org/licenses/Apache-2.0
133.. |User CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg
134 :target: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml
135.. |Caravel Build| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg
136 :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml