Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 1 | .. 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 Abbas | 3f39010 | 2022-02-21 11:59:43 +0200 | [diff] [blame] | 21 | Quick start for caravel_user_project |
| 22 | ==================================== |
Marwan Abbas | 54c22d5 | 2022-02-22 12:27:50 +0200 | [diff] [blame] | 23 | |
Marwan Abbas | 90262c4 | 2022-02-22 12:34:29 +0200 | [diff] [blame] | 24 | ------------ |
| 25 | Dependencies |
| 26 | ------------ |
| 27 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 28 | - 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 Abbas | 90262c4 | 2022-02-22 12:34:29 +0200 | [diff] [blame] | 29 | |
Marwan Abbas | d693921 | 2022-04-03 11:44:15 +0200 | [diff] [blame] | 30 | - Python 3.6+ with PIP |
| 31 | |
Marwan Abbas | 90262c4 | 2022-02-22 12:34:29 +0200 | [diff] [blame] | 32 | =============================================================================================================================================================== |
| 33 | |
| 34 | --------------------- |
| 35 | Starting your project |
| 36 | --------------------- |
| 37 | |
Marwan Abbas | e4c0d86 | 2022-07-07 14:51:02 +0200 | [diff] [blame] | 38 | #. 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 Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 39 | |
Johan Euphrosine | d5716f0 | 2022-04-04 18:53:13 +0900 | [diff] [blame] | 40 | * Follow https://github.com/efabless/caravel_user_project/generate to create a new repository. |
Marwan Abbas | d6a77e8 | 2022-07-07 14:52:31 +0200 | [diff] [blame] | 41 | * Clone the reposity using the following command: |
Marwan Abbas | f1e6e0d | 2022-07-07 13:55:16 +0200 | [diff] [blame] | 42 | |
| 43 | .. code:: bash |
| 44 | |
| 45 | git clone <your github repo URL> |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 46 | |
Marwan Abbas | e4c0d86 | 2022-07-07 14:51:02 +0200 | [diff] [blame] | 47 | #. To setup your local environment run: |
Marwan Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 48 | |
Kareem Farid | e07f662 | 2022-02-23 16:29:31 +0200 | [diff] [blame] | 49 | .. code:: bash |
Marwan Abbas | 0588de6 | 2022-02-24 19:48:38 +0200 | [diff] [blame] | 50 | |
Marwan Abbas | cad8b11 | 2022-07-07 14:45:35 +0200 | [diff] [blame] | 51 | cd <project_name> # project_name is the name of your repo |
| 52 | |
Marwan Abbas | b04fc44 | 2022-07-07 14:44:48 +0200 | [diff] [blame] | 53 | mkdir dependencies |
Marwan Abbas | 8e2bb47 | 2022-07-01 11:04:44 +0200 | [diff] [blame] | 54 | |
Marwan Abbas | b04fc44 | 2022-07-07 14:44:48 +0200 | [diff] [blame] | 55 | 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 Abbas | f1e6e0d | 2022-07-07 13:55:16 +0200 | [diff] [blame] | 58 | |
Marwan Abbas | 8e2bb47 | 2022-07-01 11:04:44 +0200 | [diff] [blame] | 59 | # export the PDK variant depending on your shuttle, if you don't know leave it to the default |
| 60 | export PDK=sky130B |
Marwan Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 61 | |
Kareem Farid | e07f662 | 2022-02-23 16:29:31 +0200 | [diff] [blame] | 62 | make setup |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 63 | |
Marwan Abbas | f1e6e0d | 2022-07-07 13:55:16 +0200 | [diff] [blame] | 64 | * This command will setup your environment by installing the following: |
Kareem Farid | e07f662 | 2022-02-23 16:29:31 +0200 | [diff] [blame] | 65 | |
| 66 | - caravel_lite (a lite version of caravel) |
| 67 | - management core for simulation |
| 68 | - openlane to harden your design |
| 69 | - pdk |
| 70 | |
Marwan Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 71 | |
Kareem Farid | e07f662 | 2022-02-23 16:29:31 +0200 | [diff] [blame] | 72 | #. Now you can start hardening your design |
Marwan Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 73 | |
Kareem Farid | e07f662 | 2022-02-23 16:29:31 +0200 | [diff] [blame] | 74 | * 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 Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 77 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 78 | .. code:: bash |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 79 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 80 | make <module_name> |
| 81 | .. |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 82 | |
Marwan Abbas | 7566d6d | 2022-02-28 18:28:14 +0200 | [diff] [blame] | 83 | 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 Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 84 | |
Kareem Farid | e07f662 | 2022-02-23 16:29:31 +0200 | [diff] [blame] | 85 | #. Integrate modules into the user_project_wrapper |
Marwan Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 86 | |
Kareem Farid | e07f662 | 2022-02-23 16:29:31 +0200 | [diff] [blame] | 87 | * 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 Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 90 | |
Kareem Farid | e07f662 | 2022-02-23 16:29:31 +0200 | [diff] [blame] | 91 | .. code:: bash |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 92 | |
Kareem Farid | e07f662 | 2022-02-23 16:29:31 +0200 | [diff] [blame] | 93 | make user_project_wrapper |
Marwan Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 94 | |
Kareem Farid | e07f662 | 2022-02-23 16:29:31 +0200 | [diff] [blame] | 95 | #. Run simulation on your design |
Marwan Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 96 | |
Kareem Farid | e07f662 | 2022-02-23 16:29:31 +0200 | [diff] [blame] | 97 | * You need to include your rtl/gl/gl+sdf files in ``verilog/includes/includes.<rtl/gl/gl+sdf>.caravel_user_project`` |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 98 | |
Kareem Farid | e07f662 | 2022-02-23 16:29:31 +0200 | [diff] [blame] | 99 | **NOTE:** You shouldn't include the files inside the verilog code |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 100 | |
Kareem Farid | e07f662 | 2022-02-23 16:29:31 +0200 | [diff] [blame] | 101 | .. code:: bash |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 102 | |
Kareem Farid | e07f662 | 2022-02-23 16:29:31 +0200 | [diff] [blame] | 103 | # 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 Abbas | e631e37 | 2022-07-01 02:34:39 -0700 | [diff] [blame] | 109 | # OR for GL+SDF simulation using |
| 110 | # sdf annotated simulation is slow |
| 111 | make verify-<testbench-name>-gl-sdf |
| 112 | |
Kareem Farid | e07f662 | 2022-02-23 16:29:31 +0200 | [diff] [blame] | 113 | # for example |
| 114 | make verify-io_ports-rtl |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 115 | |
Kareem Farid | e07f662 | 2022-02-23 16:29:31 +0200 | [diff] [blame] | 116 | #. Run the precheck locally |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 117 | |
Kareem Farid | e07f662 | 2022-02-23 16:29:31 +0200 | [diff] [blame] | 118 | .. code:: bash |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 119 | |
Kareem Farid | e07f662 | 2022-02-23 16:29:31 +0200 | [diff] [blame] | 120 | make precheck |
| 121 | make run-precheck |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 122 | |
Johan Euphrosine | d5716f0 | 2022-04-04 18:53:13 +0900 | [diff] [blame] | 123 | #. You are done! now go to https://efabless.com/open_shuttle_program/ to submit your project! |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 124 | |
| 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 |