Merge pull request #63 from efabless/documentation_updates
Documentation updates
diff --git a/README.md b/README.md
index 3706438..a44bb1f 100644
--- a/README.md
+++ b/README.md
@@ -7,5 +7,6 @@
## Please fill in your project documentation in this README.md file
+Refer to [README](docs/source/roundtrip.rst) for a complete roundtrip of how to use caravel_user_project
Refer to [README](docs/source/index.rst) for this sample project documentation.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 43caa60..052fcf7 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -67,18 +67,8 @@
git clone https://github.com/efabless/caravel_user_project.git
cd caravel_user_project
- # If unset, CARAVEL_ROOT will be set to $(pwd)/caravel
- # If you want to install caravel at a different location, run "export CARAVEL_ROOT=<caravel-path>"
- export CARAVEL_ROOT=$(pwd)/caravel
-
make install
-To update the installed caravel to the latest, run:
-
-.. code:: bash
-
- make update_caravel
-
To remove caravel, run
.. code:: bash
@@ -203,7 +193,6 @@
.. code:: bash
export PDK_ROOT=<pdk-installation-path>
- export CARAVEL_ROOT=$(pwd)/caravel
# specify simulation mode: RTL/GL
export SIM=RTL
# Run RTL simulation on IO ports testbench, make verify-io_ports
@@ -216,7 +205,6 @@
.. code:: bash
export PDK_ROOT=<pdk-installation-path>
- export CARAVEL_ROOT=$(pwd)/caravel
# specify simulation mode: RTL/GL
export SIM=GL
# Run RTL simulation on IO ports testbench, make verify-io_ports
@@ -339,6 +327,8 @@
.. code:: bash
+ # DO NOT cd into openlane
+
# Run openlane to harden user_proj_example
make user_proj_example
# Run openlane to harden user_project_wrapper
@@ -362,12 +352,9 @@
Then, you can run the precheck by running
-Specify CARAVEL_ROOT before running any of the following,
.. code:: bash
- # export CARAVEL_ROOT=$(pwd)/caravel
- export CARAVEL_ROOT=<path-to-caravel>
make run-precheck
This will run all the precheck checks on your project and will produce the logs under the ``checks`` directory.
@@ -380,13 +367,6 @@
Run ``make help`` to display available targets.
-Specify CARAVEL_ROOT before running any of the following,
-
-.. code:: bash
-
- # export CARAVEL_ROOT=$(pwd)/caravel
- export CARAVEL_ROOT=<path-to-caravel>
-
Run lvs on the mag view,
.. code:: bash
@@ -422,6 +402,8 @@
.. code:: bash
make xor-wrapper
+
+
Checklist for Open-MPW Submission
diff --git a/docs/source/roundtrip.rst b/docs/source/roundtrip.rst
new file mode 100644
index 0000000..cc68ebc
--- /dev/null
+++ b/docs/source/roundtrip.rst
@@ -0,0 +1,120 @@
+.. raw:: html
+
+ <!---
+ # SPDX-FileCopyrightText: 2020 Efabless Corporation
+ #
+ # Licensed under the Apache License, Version 2.0 (the "License");
+ # you may not use this file except in compliance with the License.
+ # You may obtain a copy of the License at
+ #
+ # http://www.apache.org/licenses/LICENSE-2.0
+ #
+ # Unless required by applicable law or agreed to in writing, software
+ # distributed under the License is distributed on an "AS IS" BASIS,
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ # See the License for the specific language governing permissions and
+ # limitations under the License.
+ #
+ # SPDX-License-Identifier: Apache-2.0
+ -->
+
+Complete roundtrip for caravel_user_project
+===========================================
+
+1. 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
+
+2. Open your Terminal. Create an empty folder to use as your Caravel workspace, and navigate to it.
+
+.. code:: bash
+
+ # Create a directory and call it anything you want
+ mkdir -p caravel_tutorial
+
+ # navigate into the directory
+ cd caravel_tutorial
+
+3. Clone caravel_user_project and setup the git environment as follows
+
+.. code:: bash
+
+ # Make sure that ``caravel_example`` matches the empty github repo name in step 1
+ git clone -b mpw-5 https://github.com/efabless/caravel_user_project caravel_example
+ cd caravel_example
+ git remote rename origin upstream
+
+ # You need to put your empty github repo URL from step 1
+ git remote add origin <your github repo URL>
+
+ # Create a new branch, you can name it anything
+ git checkout -b <my_branch>
+ git push -u origin <my_branch>
+
+4. Now that your git environment is setup, it's time to setup your local environment
+
+.. code:: bash
+
+ # to install caravel-lite into your caravel_user_project
+ # you can install full caravel (not recommended) use ``export CARAVEL_LITE=0``
+ make install
+
+ # The default for the management core is litex, to install the pico version use
+ export MCW=pico
+ # To install the management core for simulation
+ make install_mcw
+
+
+
+ # To clone the management core pico for simulation
+ git clone git@github.com:efabless/caravel_pico.git
+
+ # Install openlane for hardening your project
+ # make sure to change <directory_name> with the directory you created in step 1
+ # in this case it is caravel_tutorial
+ export OPENLANE_ROOT=~/<directory_name>/openlane # you need to export this whenever you start a new shell
+ make openlane
+
+ # Build the pdk
+ # make sure to change <directory_name> with the directory you created in step 1
+ # in this case it is caravel_tutorial
+ export PDK_ROOT=~/<directory_name>/pdks # you need to export this whenever you start a new shell
+ make pdk
+
+5. Now you can start hardening your design, for example
+
+.. code:: bash
+
+ make user_proj_example
+ make user_project_wrapper
+
+6. To run simulation on your design
+
+.. code:: bash
+
+ make simenv
+ # you can run RTL/GL simulations by using
+ export SIM=RTL
+ # OR
+ export SIM=GL
+
+ # you can then run the simulations using
+ make verify-<testbench-name>
+
+ # for example
+ make verify-io_ports
+
+7. To run the precheck locally
+
+.. code:: bash
+
+ make precheck
+ make run-precheck
+
+17. You are done! now go to www.efabless.com to submit your project!
+
+
+.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
+ :target: https://opensource.org/licenses/Apache-2.0
+.. |User CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg
+ :target: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml
+.. |Caravel Build| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg
+ :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml
