blob: 6a5c29276501581567fa8ddd32c31efd4234bb91 [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
Marwan Abbasd6939212022-04-03 11:44:15 +020030- Python 3.6+ with PIP
31
Marwan Abbas90262c42022-02-22 12:34:29 +020032===============================================================================================================================================================
33
34---------------------
35Starting your project
36---------------------
37
Marwan Abbase4c0d862022-07-07 14:51:02 +020038#. To start the project you first need to create a new repository based on the `caravel_user_project <https://github.com/efabless/caravel_user_project/>`_ template and make sure your repo is public and includes a README.
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080039
Johan Euphrosined5716f02022-04-04 18:53:13 +090040 * Follow https://github.com/efabless/caravel_user_project/generate to create a new repository.
Marwan Abbasd6a77e82022-07-07 14:52:31 +020041 * Clone the reposity using the following command:
Marwan Abbasf1e6e0d2022-07-07 13:55:16 +020042
43 .. code:: bash
44
45 git clone <your github repo URL>
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080046
Marwan Abbase4c0d862022-07-07 14:51:02 +020047#. To setup your local environment run:
Marwan Abbasfdff8582022-02-22 17:05:31 +020048
Kareem Faride07f6622022-02-23 16:29:31 +020049 .. code:: bash
Marwan Abbas0588de62022-02-24 19:48:38 +020050
Marwan Abbascad8b112022-07-07 14:45:35 +020051 cd <project_name> # project_name is the name of your repo
52
Marwan Abbasb04fc442022-07-07 14:44:48 +020053 mkdir dependencies
Marwan Abbas8e2bb472022-07-01 11:04:44 +020054
Marwan Abbasb04fc442022-07-07 14:44:48 +020055 export OPENLANE_ROOT=$(pwd)/dependencies/openlane_src # you need to export this whenever you start a new shell
56
57 export PDK_ROOT=$(pwd)/dependencies/pdks # you need to export this whenever you start a new shell
Marwan Abbasf1e6e0d2022-07-07 13:55:16 +020058
Marwan Abbas8e2bb472022-07-01 11:04:44 +020059 # export the PDK variant depending on your shuttle, if you don't know leave it to the default
60 export PDK=sky130B
Marwan Abbasfdff8582022-02-22 17:05:31 +020061
jeffdifafaea52022-10-18 22:23:38 -070062 # for the GFMPW shuttles...
63 export PDK=gf180mcu
64
Kareem Faride07f6622022-02-23 16:29:31 +020065 make setup
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020066
Marwan Abbasf1e6e0d2022-07-07 13:55:16 +020067* This command will setup your environment by installing the following:
Kareem Faride07f6622022-02-23 16:29:31 +020068
69 - caravel_lite (a lite version of caravel)
70 - management core for simulation
71 - openlane to harden your design
72 - pdk
73
Marwan Abbasfdff8582022-02-22 17:05:31 +020074
Kareem Faride07f6622022-02-23 16:29:31 +020075#. Now you can start hardening your design
Marwan Abbasfdff8582022-02-22 17:05:31 +020076
Kareem Faride07f6622022-02-23 16:29:31 +020077 * To start hardening you project you need
78 - RTL verilog model for your design for OpenLane to harden
79 - 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 +020080
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020081 .. code:: bash
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080082
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020083 make <module_name>
84 ..
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080085
Marwan Abbas7566d6d2022-02-28 18:28:14 +020086 For an example of hardening a project please refer to `user_project_example <https://github.com/efabless/caravel_user_project/blob/main/docs/source/index.rst#hardening-the-user-project-using-openlane>`_
Marwan Abbasfdff8582022-02-22 17:05:31 +020087
Kareem Faride07f6622022-02-23 16:29:31 +020088#. Integrate modules into the user_project_wrapper
Marwan Abbasfdff8582022-02-22 17:05:31 +020089
Kareem Faride07f6622022-02-23 16:29:31 +020090 * 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
91 * Instantiate your module(s) in ``verilog/rtl/user_project_wrapper.v``
92 * Harden the user_project_wrapper including your module(s), using this command:
Marwan Abbasfdff8582022-02-22 17:05:31 +020093
Kareem Faride07f6622022-02-23 16:29:31 +020094 .. code:: bash
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080095
Kareem Faride07f6622022-02-23 16:29:31 +020096 make user_project_wrapper
Marwan Abbasfdff8582022-02-22 17:05:31 +020097
Kareem Faride07f6622022-02-23 16:29:31 +020098#. Run simulation on your design
Marwan Abbasfdff8582022-02-22 17:05:31 +020099
Kareem Faride07f6622022-02-23 16:29:31 +0200100 * You need to include your rtl/gl/gl+sdf files in ``verilog/includes/includes.<rtl/gl/gl+sdf>.caravel_user_project``
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800101
Kareem Faride07f6622022-02-23 16:29:31 +0200102 **NOTE:** You shouldn't include the files inside the verilog code
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800103
Kareem Faride07f6622022-02-23 16:29:31 +0200104 .. code:: bash
Marwan Abbas7ccab9c2022-02-23 14:30:41 +0200105
Kareem Faride07f6622022-02-23 16:29:31 +0200106 # you can then run RTL simulations using
107 make verify-<testbench-name>-rtl
108
109 # OR GL simulation using
110 make verify-<testbench-name>-gl
111
Marwan Abbase631e372022-07-01 02:34:39 -0700112 # OR for GL+SDF simulation using
113 # sdf annotated simulation is slow
114 make verify-<testbench-name>-gl-sdf
115
Kareem Faride07f6622022-02-23 16:29:31 +0200116 # for example
117 make verify-io_ports-rtl
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800118
Kareem Faride07f6622022-02-23 16:29:31 +0200119#. Run the precheck locally
Marwan Abbas7ccab9c2022-02-23 14:30:41 +0200120
Kareem Faride07f6622022-02-23 16:29:31 +0200121 .. code:: bash
Marwan Abbas7ccab9c2022-02-23 14:30:41 +0200122
Kareem Faride07f6622022-02-23 16:29:31 +0200123 make precheck
124 make run-precheck
Marwan Abbas7ccab9c2022-02-23 14:30:41 +0200125
Johan Euphrosined5716f02022-04-04 18:53:13 +0900126#. You are done! now go to https://efabless.com/open_shuttle_program/ to submit your project!
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800127
128
129.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
130 :target: https://opensource.org/licenses/Apache-2.0
131.. |User CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg
132 :target: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml
133.. |Caravel Build| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg
134 :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml