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 start the project you first need to create a new repository based on the caravel_user_project template and make sure your repo is public and includes a README.
Follow https://github.com/efabless/caravel_user_project/generate to create a new repository.
Clone the reposity using the following command:
git clone <your github repo URL>
To setup your local environment run:
cd <project_name> # project_name is the name of your repo # export the PDK variant depending on your shuttle, if you don't know leave it to the default # for sky130 MPW shuttles.... export PDK=sky130A # for the gf180 GFMPW shuttles... export PDK=gf180mcuC make setup
Now you can start hardening your design
To start hardening you project you need - RTL verilog model for your design for OpenLane to harden - A subdirectory for each macro in your project under
openlane/ directory, each subdirectory should include openlane configuration files for the macro
For an example of hardening a project please refer to Hardening the User Project using OpenLane. .
Integrate modules into the user_project_wrapper
Change the environment variables
openlane/user_project_wrapper/config.tcl to point to your module
Instantiate your module(s) in
Harden the user_project_wrapper including your module(s), using this command:
Run simulation on your design
NOTE: You shouldn't include the files inside the verilog code# you can then run RTL simulations using make verify-<testbench-name>-rtl # OR GL simulation using make verify-<testbench-name>-gl # OR for GL+SDF simulation using # sdf annotated simulation is slow make verify-<testbench-name>-gl-sdf # for example make verify-io_ports-rtl
Run opensta on your design
Extract spefs for
user_project_wrapper and macros inside it:
Create spef mapping file that maps instance names to spef files:
NOTE: To update timing scripts run
Run standalone LVS
make lvs-<macro_name> # macro is the name of the macro you want to run LVS on
NOTE: You have to create a new config file for each macro under
Run the precheck locally
make precheck make run-precheck
You are done! now go to https://efabless.com/open_shuttle_program/ to submit your project!
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
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.
You are required to specify the power-on default configuration for each GPIO in Caravel. The default configuration provide the state the GPIO will come up on power up. The configuration can be changed by the management SoC during firmware execution.
Configuration settings define whether the GPIO is configured to connect to the user project area or the managment SoC. They also determine whether IOs are inputs or outputs, digital or analog, as well as whether pull-up or pull-down resistors are configured for inputs.
GPIOs are configured by assigning predefined values for each IO in the file verilog/rtl/user_defines.v in your project.
You need to assigned configuration values for GPIO thru GPIO.
GPIO thru GPIO are preset and cannot be changed.
The following values are redefined for assigning to GPIOs.
MPW_Prececk includes a check to confirm each GPIO is assigned a valid value.
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 .
First, you will need to install the simulation environment, by
This will pull a docker image with the needed tools installed.
Then, run the RTL simulation by
export PDK_ROOT=<pdk-installation-path> make verify-<testbench-name>-rtl # For example make verify-io_ports-rtl
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> make verify-<testbench-name>-gl # For example make verify-io_ports-gl
To make sure that your design is timing clean, one way is running sdf annotated gate-level simulation Run the sdf annotated gate-level simulation by:
export PDK_ROOT=<pdk-installation-path> make verify-<testbench-name>-gl-sdf # For example make verify-io_ports-gl-sdf
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 must match the golden user_project_wrapper in the following:
(2.920um x 3.520um)
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.
For the design to pass precheck, a custom lvs configuration file for your design is needed, config file can be found under lvs/<design_name>/lvs_config.json
The lvs_config.json files are a possibly hierarchical set of files to set parameters for device level LVS
Required variables: - TOP_SOURCE : Top source cell name. - TOP_LAYOUT : Top layout cell name. - LAYOUT_FILE : Layout gds data file. - LVS_SPICE_FILES : A list of spice files. - LVS_VERILOG_FILES : A list of verilog files. Note: files with child modules should be listed before parent modules. Not needed for purely analog designs.
Files must be defined as a absolute path beginning with a shell variable such as $PDK_ROOT or $UPRJ_ROOT.
Optional variable lists: Hierarchical config files: - INCLUDE_CONFIGS : List of configuration files to read recursively.
Extraction related. * may be used as a wild card character. - EXTRACT_FLATGLOB : List of cell names to flatten before extraction.
Cells without text tend to work better if flattened. Note: it is necessary to flatten all sub cells of any cells listed.
LVS related. * may be used as a wild card character. - LVS_FLATTEN : List of cells to flatten before comparing,
Sometimes matching topologies with mismatched pins cause errors at a higher level. Flattening these cells can yield a match.
NOTE: Missing files and undefined variables result in fatal errors.
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
This will run all the precheck checks on your project and will produce the logs under the
To disable running LVS/Soft/ERC connection checks:
DISABLE_LVS=1 make run-precheck
Start by updating the Makefile for your project. Starting in the project root...
curl -k https://raw.githubusercontent.com/efabless/caravel_user_project/main/Makefile > Makefile make setup-timing-scripts make install make install_mcw
This will update Caravel design files and install the scripts for running timing.
Then, you can run then run timing by the following...
make extract-parasitics make create-spef-mapping make caravel-sta
A summary of timing results is provided at the end of the flow.
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.
make help to display available targets.
Run lvs on the mag view,
Run lvs on the gds,
Run lvs on the maglef,
Run drc using magic,
Run antenna check using magic,
Run XOR check,
user_project_wrapperadheres to the same pin order specified at pin_order
user_project_wrapperadheres to the fixed wrapper configuration specified at fixed_wrapper_cfgs
May 20, 2021