blob: 86bf7e05ca90b59f7100b62c118512dc02cad088 [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
Kareem Faride07f6622022-02-23 16:29:31 +020062 make setup
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020063
Marwan Abbasf1e6e0d2022-07-07 13:55:16 +020064* This command will setup your environment by installing the following:
Kareem Faride07f6622022-02-23 16:29:31 +020065
66 - caravel_lite (a lite version of caravel)
67 - management core for simulation
68 - openlane to harden your design
69 - pdk
70
Marwan Abbasfdff8582022-02-22 17:05:31 +020071
Kareem Faride07f6622022-02-23 16:29:31 +020072#. Now you can start hardening your design
Marwan Abbasfdff8582022-02-22 17:05:31 +020073
Kareem Faride07f6622022-02-23 16:29:31 +020074 * To start hardening you project you need
75 - RTL verilog model for your design for OpenLane to harden
76 - 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 +020077
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020078 .. code:: bash
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080079
Marwan Abbas7ccab9c2022-02-23 14:30:41 +020080 make <module_name>
81 ..
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080082
Marwan Abbas7566d6d2022-02-28 18:28:14 +020083 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 +020084
Kareem Faride07f6622022-02-23 16:29:31 +020085#. Integrate modules into the user_project_wrapper
Marwan Abbasfdff8582022-02-22 17:05:31 +020086
Kareem Faride07f6622022-02-23 16:29:31 +020087 * 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
88 * Instantiate your module(s) in ``verilog/rtl/user_project_wrapper.v``
89 * Harden the user_project_wrapper including your module(s), using this command:
Marwan Abbasfdff8582022-02-22 17:05:31 +020090
Kareem Faride07f6622022-02-23 16:29:31 +020091 .. code:: bash
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080092
Kareem Faride07f6622022-02-23 16:29:31 +020093 make user_project_wrapper
Marwan Abbasfdff8582022-02-22 17:05:31 +020094
Kareem Faride07f6622022-02-23 16:29:31 +020095#. Run simulation on your design
Marwan Abbasfdff8582022-02-22 17:05:31 +020096
Kareem Faride07f6622022-02-23 16:29:31 +020097 * 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 -080098
Kareem Faride07f6622022-02-23 16:29:31 +020099 **NOTE:** You shouldn't include the files inside the verilog code
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800100
Kareem Faride07f6622022-02-23 16:29:31 +0200101 .. code:: bash
Marwan Abbas7ccab9c2022-02-23 14:30:41 +0200102
Kareem Faride07f6622022-02-23 16:29:31 +0200103 # you can then run RTL simulations using
104 make verify-<testbench-name>-rtl
105
106 # OR GL simulation using
107 make verify-<testbench-name>-gl
108
Marwan Abbase631e372022-07-01 02:34:39 -0700109 # OR for GL+SDF simulation using
110 # sdf annotated simulation is slow
111 make verify-<testbench-name>-gl-sdf
112
Kareem Faride07f6622022-02-23 16:29:31 +0200113 # for example
114 make verify-io_ports-rtl
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800115
Kareem Faride07f6622022-02-23 16:29:31 +0200116#. Run the precheck locally
Marwan Abbas7ccab9c2022-02-23 14:30:41 +0200117
Kareem Faride07f6622022-02-23 16:29:31 +0200118 .. code:: bash
Marwan Abbas7ccab9c2022-02-23 14:30:41 +0200119
Kareem Faride07f6622022-02-23 16:29:31 +0200120 make precheck
121 make run-precheck
Marwan Abbas7ccab9c2022-02-23 14:30:41 +0200122
Johan Euphrosined5716f02022-04-04 18:53:13 +0900123#. You are done! now go to https://efabless.com/open_shuttle_program/ to submit your project!
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800124
125
126.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
127 :target: https://opensource.org/licenses/Apache-2.0
128.. |User CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg
129 :target: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml
130.. |Caravel Build| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg
131 :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml