Efabless Logo

Caravel User Project


Caravel User Project

License User CI Caravel Build

Table of contents


Caravel User Project provides a template for implementing designs using Caravel compatible with the Open MPW Shuttle program and chipIgnite.

This version is intended for user on the Efabless platform within a user virtual desktop.

The project implement in this example is a simple counter that showcases how to make use of user space utilities Caravel's like IO pads, logic analyzer probes, and wishbone port. It also demonstrates the required structure for the open-mpw shuttle projects.

The virtual desktop already provides all tools required for design and verification including the OpenLane design flow, Magic, Klayout, Netgen, Ngspice, and Xschem.  These tools do not need to ( and can not ) be installed in the desktop by users.  The  desktop also include an installation of the SKY130 pdk.

Caravel Integration

Verilog Integration

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:

  • The IO ports for displaying the count register values on the IO pads.
  • The LA probes for supplying an optional reset and clock signals and for setting an initial value for the count register.
  • The wishbone port for reading/writing the count value through the management SoC.

Refer to user_project_wrapper for more information.


Layout Integration

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 .

Running Full Chip Simulation

Then, run the RTL simulation by

# 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:

# 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.

User Project Wrapper Requirements

Your hardened user_project_wrapper must match the golden user_project_wrapper in the following:

  • Area (2.920um x 3.520um)
  • Top module name "user_project_wrapper"
  • Pin Placement
  • Pin Sizes
  • Core Rings Width and Offset
  • PDN Vertical and Horizontal Straps Width

You are allowed to change the following if you need to:

  • PDN Vertical and Horizontal Pitch & Offset

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.

Hardening the User Project using OpenLane

Hardening Options

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
pic1 pic2 pic3
ex: caravel_user_project   ex: caravel_ibex

For more details on hardening macros using openlane, refer to README.

Running OpenLane

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.

Running MPW Precheck Locally

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.

Other Miscellaneous Targets

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

Checklist for Open-MPW Submission

  • ✔️ The project repo adheres to the same directory structure in this repo.
  • ✔️ The project repo contain info.yaml at the project root.
  • ✔️ Top level macro is named user_project_wrapper.
  • ✔️ Full Chip Simulation passes for RTL and GL (gate-level)
  • ✔️ The hardened Macros are LVS and DRC clean
  • ✔️ The project contains a gate-level netlist for user_project_wrapper at verilog/gl/user_project_wrapper.v
  • ✔️ The hardened user_project_wrapper adheres to the same pin order specified at pin_order
  • ✔️ The hardened user_project_wrapper adheres to the fixed wrapper configuration specified at fixed_wrapper_cfgs
  • ✔️ XOR check passes with zero total difference.
  • ✔️ Openlane summary reports are retained under ./signoff/
  • ✔️ The design passes the mpw-precheck
  • SKY130 Open PDK
  • 38 programable IO's
  • 10 sq mm user design space


Catalog ID





Efabless engineering

















Contact Designer




Library Package



Version Date

May 20, 2021