blob: 58d7af743390cb41e1d21a33dee05dd066aab428 [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## Dependencies
24
25- 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 Apple Chip](https://desktop.docker.com/mac/main/arm64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=dd-smartbutton&utm_location=header)
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080026
271. 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
28
292. Open your Terminal. Create an empty folder to use as your Caravel workspace, and navigate to it.
30
31.. code:: bash
32
33 # Create a directory and call it anything you want
34 mkdir -p caravel_tutorial
35
36 # navigate into the directory
37 cd caravel_tutorial
38
393. Clone caravel_user_project and setup the git environment as follows
40
41.. code:: bash
42
43 # Make sure that ``caravel_example`` matches the empty github repo name in step 1
Marwan Abbasceb04452022-02-20 21:26:07 +020044 git clone -b mpw-5b https://github.com/efabless/caravel_user_project caravel_example
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080045 cd caravel_example
46 git remote rename origin upstream
47
48 # You need to put your empty github repo URL from step 1
49 git remote add origin <your github repo URL>
50
51 # Create a new branch, you can name it anything
52 git checkout -b <my_branch>
53 git push -u origin <my_branch>
54
Marwan Abbas54c22d52022-02-22 12:27:50 +0200554. Now that your git environment is setup, it's time to setup your local environment.
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080056
57.. code:: bash
58
59 # to install caravel-lite into your caravel_user_project
60 # you can install full caravel (not recommended) use ``export CARAVEL_LITE=0``
61 make install
kareemb104c942022-02-15 06:05:35 -080062
kareemb104c942022-02-15 06:05:35 -080063 # To install the management core for simulation
64 make install_mcw
65
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080066 # Install openlane for hardening your project
Marwan Abbasb579e002022-02-17 10:13:24 +020067 # make sure to change <directory_name> with the directory you created in step 2 (In this case it's caravel_tutorial)
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080068 # in this case it is caravel_tutorial
69 export OPENLANE_ROOT=~/<directory_name>/openlane # you need to export this whenever you start a new shell
70 make openlane
71
72 # Build the pdk
73 # make sure to change <directory_name> with the directory you created in step 1
74 # in this case it is caravel_tutorial
Marwan Abbas75ba5732022-02-11 16:50:50 +020075
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080076 export PDK_ROOT=~/<directory_name>/pdks # you need to export this whenever you start a new shell
77 make pdk
78
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800795. Now you can start hardening your design, for example
80
81.. code:: bash
82
83 make user_proj_example
84 make user_project_wrapper
85
866. To run simulation on your design
87
88.. code:: bash
89
90 make simenv
91 # you can run RTL/GL simulations by using
92 export SIM=RTL
93 # OR
94 export SIM=GL
95
96 # you can then run the simulations using
97 make verify-<testbench-name>
98
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -080099 # for example
100 make verify-io_ports
101
1027. To run the precheck locally
103
104.. code:: bash
105
106 make precheck
107 make run-precheck
108
10917. You are done! now go to www.efabless.com to submit your project!
110
111
112.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
113 :target: https://opensource.org/licenses/Apache-2.0
114.. |User CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg
115 :target: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml
116.. |Caravel Build| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg
117 :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml