This repo contains a sample user project that utilizes the caravel chip user space. The user project is a simple counter that showcases how to make use of caravel's user space utilities like IO pads, logic analyzer probes, and wishbone port. The repo also demonstrates the recommended structure for the open-mpw shuttle projects.
To setup caravel, run the following:
git clone https://github.com/efabless/caravel_user_project.git
cd caravel_user_project
make install
To remove caravel, run
make uninstall
By default caravel-lite is installed. To install the full version of caravel, run this prior to calling make install.
export CARAVEL_LITE=0
Caravel files are kept separate from the user project by having caravel as submodule. The submodule commit should point to the latest of caravel/caravel-lite master/main branch. The following files should have a symbolic link to caravel's corresponding files:
The symbolic links are automatically set when you run make install
.
You need to create a wrapper around your macro that adheres to the template at user_project_wrapper. The wrapper top module must be named user_project_wrapper
and must have the same input and output ports as the golden wrapper template. The wrapper gives access to the user space utilities provided by caravel like IO ports, logic analyzer probes, and wishbone bus connection to the management SoC.
For this sample project, the user macro makes use of:
Refer to user_project_wrapper for more information.
The caravel layout is pre-designed with an empty golden wrapper in the user space. You only need to provide us with a valid user_project_wrapper
GDS file. And, as part of the tapeout process, your hardened user_project_wrapper
will be inserted into a vanilla caravel layout to get the final layout shipped for fabrication.
To make sure that this integration process goes smoothly without having any DRC or LVS issues, your hardened user_project_wrapper
must adhere to a number of requirements listed at User Project Wrapper Requirements .
Make sure you have Magic VLSI Layout Tool installed on your machine before building the pdk. The pdk build is tested with magic version 8.3.265
.
# set PDK_ROOT to the path you wish to use for the pdk
export PDK_ROOT=<pdk-installation-path>
# you can optionally specify skywater-pdk and open-pdks commit used
# by setting and exporting SKYWATER_COMMIT and OPEN_PDKS_COMMIT
# if you do not set them, they default to the last verfied commits tested for this project
make pdk
First, you will need to install the simulation environment, by
make simenv
This will pull a docker image with the needed tools installed.
Then, run the RTL simulation by
export PDK_ROOT=<pdk-installation-path>
# specify simulation mode: RTL/GL
export SIM=RTL
# Run RTL simulation on IO ports testbench, make verify-io_ports
make verify-<testbench-name>
Once you have the physical implementation done and you have the gate-level netlists ready, it is crucial to run full gate-level simulations to make sure that your design works as intended after running the physical implementation.
Run the gate-level simulation by:
export PDK_ROOT=<pdk-installation-path>
# specify simulation mode: RTL/GL
export SIM=GL
# Run RTL simulation on IO ports testbench, make verify-io_ports
make verify-<testbench-name>
This sample project comes with four example testbenches to test the IO port connection, wishbone interface, and logic analyzer. The test-benches are under the verilog/dv directory. For more information on setting up the simulation environment and the available testbenches for this sample project, refer to README.
Your hardened user_project_wrapper
must match the golden user_project_wrapper in the following:
(2.920um x 3.520um)
"user_project_wrapper"
You are allowed to change the following if you need to:
To make sure that you adhere to these requirements, we run an exclusive-or (XOR) check between your hardened user_project_wrapper
GDS and the golden wrapper GDS after processing both layouts to include only the boundary (pins and core rings). This check is done as part of the mpw-precheck tool.
You will need to install openlane by running the following
export OPENLANE_ROOT=<openlane-installation-path>
# you can optionally specify the openlane tag to use
# by running: export OPENLANE_TAG=<openlane-tag>
# if you do not set the tag, it defaults to the last verfied tag tested for this project
make openlane
For detailed instructions on the openlane and the pdk installation refer to README.
There are three options for hardening the user project macro using openlane:
Option 1 | Option 2 | Option 3 |
---|---|---|
Hardening the user macro(s) first, then inserting it in the user project wrapper with no standard cells on the top level | Flattening the user macro(s) with the user_project_wrapper | Placing multiple macros in the wrapper along with standard cells on the top level |
![]() |
![]() |
![]() |
ex: caravel_user_project | ex: caravel_ibex |
For more details on hardening macros using openlane, refer to README.
For this sample project, we went for the first option where the user macro is hardened first, then it is inserted in the user project wrapper without having any standard cells on the top level.
To reproduce hardening this project, run the following:
# DO NOT cd into openlane
# Run openlane to harden user_proj_example
make user_proj_example
# Run openlane to harden user_project_wrapper
make user_project_wrapper
For more information on the openlane flow, check README.
You can install the mpw-precheck by running
# By default, this install the precheck in your home directory
# To change the installtion path, run "export PRECHECK_ROOT=<precheck installation path>"
make precheck
This will clone the precheck repo and pull the latest precheck docker image.
Then, you can run the precheck by running
make run-precheck
This will run all the precheck checks on your project and will produce the logs under the checks
directory.
The makefile provides a number of useful that targets that can run LVS, DRC, and XOR checks on your hardened design outside of openlane's flow.
Run make help
to display available targets.
Run lvs on the mag view,
make lvs-<macro_name>
Run lvs on the gds,
make lvs-gds-<macro_name>
Run lvs on the maglef,
make lvs-maglef-<macro_name>
Run drc using magic,
make drc-<macro_name>
Run antenna check using magic,
make antenna-<macro_name>
Run XOR check,
make xor-wrapper
user_project_wrapper
.user_project_wrapper
at verilog/gl/user_project_wrapper.vuser_project_wrapper
adheres to the same pin order specified at pin_orderuser_project_wrapper
adheres to the fixed wrapper configuration specified at fixed_wrapper_cfgsHardware implementation of the Hack Computer from the Nand to Tetris courses
1.0
processor
sky130A