• Project Description
• Caravel
• Openlane
• SPM Design
• Wishbone Communication
• Design Implementation
• Design Simulation

In this project we will be building on the Caravel User Project and show how we can use the template to harden our design a Serial-Parallel-Multiplier (SPM) and integrate it within the caravel chip.

Caravel is a template SoC for Efabless Open MPW and chipIgnite shuttles based on the Sky130 node from SkyWater Technologies. It provides a wrapper for the user project area where the user can add their own designs.

As shown in the above figure, caravel is composed of the harness frame plus two wrappers for drop-in modules for the management area and user project area. Our project will reside in the user project wrapper and it has access to the following utilities provided by the management SoC:

• 38 IO Ports
• 128 Logic analyzer probes
• Wishbone port connection to the management SoC wishbone bus.

We will be using the wishbone bus as the communication channel between the management SoC and the SPM, more on that here.

Openlane is an automated RTL to GDSII flow based on several components including OpenROAD, Yosys, Magic, Netgen, CVC, SPEF-Extractor, CU-GR, Klayout and a number of custom scripts for design exploration and optimization. The flow performs full ASIC implementation steps from RTL all the way down to GDSII. The architecture of Openlane:

When hardening your design using OpenLane, there are 3 available options to use:

• The first option is hardening your design, then inserting the hardened design in the user project wrapper, then hardening the user project wrapper. This is the option that is chosen by default.

• The second option is flattening the user macro(s) with the user_project_wrapper then hardening everything altogether in one step.

• The third option is a mix of both using some hardened macros and other flattened ones with the same warpper. Check the example of caravel_ibex as a reference for this technique.

SPM stands for serial parallel multiplier, where it takes two 32-bit numbers and performs multiplication to produce a 64-bit product.

The design consists of 3 different modules:

• spm.v
  
• mul32.v
  
• user_proj_mul32.v
  

As shown below, the first module spm.v receives a 32-bit input standing for the multiplicand (x), then with each clock cycle, one bit is being read from the multiplier (y), and one bit from the product (p) is calculated and sent as an output. This module is instantiated from mul32.v.

The second module mul32.v is instantiated from user_proj_mul32.v. It receives the multiplier (mp) and the multiplicand (mc) and is responsible for shifting the multiplier to the right each clock cycle and feeding its least significant bit to the spm module. It also takes the spm output (p), concatenates it to the final output and shifts it to the right until the multiplication process is done (64 clock cycles). The module receives a start signal when the two numbers are ready to be multiplied and sends the final product along with a done signal when the process is finished. Its block diagram:

The third module and its the top module of our project is user_proj_mul32.v. This module is the one instantiated inside the User’s Project Wrapper. It is important to note that any User’s Project should have a fixed set of ports as you can find the verilog code. In summary, this module is responsible for communicating with the caravel's management core through the wishbone bus (more on that here). Below are the module's block diagram along with the user_project_wrapper.v block diagram:

We implement the SPM in the user project area as a peripheral that can be accessed by firmware on the management SoC. The management core communicates with the SPM using the wishbone bus, there are other ways of communication such as the Logic Analyzer (LA) signals, however, in this project, only the wishbone communication is going to be discussed.

As shown in the caravel architecture, the management core exposes the wishbone bus to the user’s project area. This wishbone bus is used for communication between the management core and the peripheral implemented in the user’s project area. In this case, the management core is called a “master” and the peripheral in the user’s project area is called a “$lave”. The reason for that is that the management core is the one initiating any read or write operation. The wishbone bus is a shared bus among all the peripherals in the user’s project area, which means that at any point in time, the management core can communicate with only one $lave in the user’s project area.

As shown in the above figure, the user’s project area in our case has 4 registers, where each one is considered a $lave. These registers correspond to the multiplicand, the multiplier and 2 registers for the product since the wishbone bus has a data bus of width 32 bits only. The registers are memory-mapped, which means that they can be accessed using addresses in the memory. The addresses used for these 4 variables are shown in the below table:

There are 10 signals used to write/read to a wishbone $lave port that are summarized in the below table:

The above table explains what each signal means in a wishbone $lave and how each signal can be used. In the figure below, it shows a $lave port register for MP and MC in the SPM. This figure is not valid for the Product registers (register storing the product) since the ack signal when reading from P is dependent on the completeness of the multiplication operation as well.

In this section we will discuss the steps needed to start your project, setup your environment, then harden the design along with the wrapper. We will be using the first technique while hardening; which is hardening the design first then inserting the hardened design in the user project wrapper, then hardening the user project wrapper.

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

2. To setup your local environment run:

cd <project_name> # project_name is the name of your repo

mkdir dependencies

export OPENLANE_ROOT=$(pwd)/dependencies/openlane_src # you need to export this whenever you start a new shell

export PDK_ROOT=$(pwd)/dependencies/pdks # you need to export this whenever you start a new shell

# export the PDK variant depending on your shuttle, if you don't know leave it to the default
export PDK=sky130B

make setup

• This command will setup your environment by installing the following:
  • caravel_lite (a lite version of caravel)
  • management core for simulation
  • openlane to harden your design
  • pdk

3. The environment is now ready we can start adding our SPM Design files; copy the design's source files spm.v, mul32.v, user_proj_mul32.v into <project_name>/verilog/rtl
   

4. To Harden the design using Openlane you need to:

• Navigate <project_name>/openlane folder to make a copy of the forder user_proj_example into user_proj_mul32.
  
• Edit to the configurations file config.tcl in the user_proj_mul32 folder that you just created as follows:

##### Change the design name
set ::env(DESIGN_NAME) user_proj_mul32

##### Specify the design files
set ::env(VERILOG_FILES) "\
  $::env(CARAVEL_ROOT)/verilog/rtl/defines.v \
  $script_dir/../../verilog/rtl/user_proj_mul32.v \
  $script_dir/../../verilog/rtl/mul32.v \
  $script_dir/../../verilog/rtl/spm.v"

##### Disable basic placement
# set ::env(PL_BASIC_PLACEMENT) 1

##### Increase the target density:
set ::env(PL_TARGET_DENSITY) 0.35

To learn more about openlane configurations check out this documentation

• Now our design is ready to be hardened; inside the folder caravel_user_project, run the following command

make user_proj_mul32

5. Now that our design is hardened, we need to harden the project wrapper

• Go to the folder caravel_user_project/verilog/rtl an edit the file user_project_wrapper.v to change the module being instantiated from user_proj_example to user_proj_mul32.
• Edit the wrapper's configurations file config.tcl under <project_name>/openlane/user_project_wrapper as follows:

##### Black-box verilog and views 
set ::env(VERILOG_FILES_BLACKBOX) "\
	$::env(CARAVEL_ROOT)/verilog/rtl/defines.v \
	$script_dir/../../verilog/rtl/user_proj_mul32.v"

set ::env(EXTRA_LEFS) "\
	$script_dir/../../lef/user_proj_mul32.lef"

set ::env(EXTRA_GDS_FILES) "\
	$script_dir/../../gds/user_proj_mul32.gds"

##### Add the following line 
set ::env(GLB_RT_ADJUSTMENT) 0.1

• Now you can harden the project wrapper; inside the folder caravel_user_project, run the following command

make user_project_wrapper

• The make <design_name> command starts the ASIC flow to produce the layout in GDS2 format starting from the design HDL files. When the flow finishes, you should see the message:

[SUCCESS]: Flow complete.

• As the flow runs, it produces lots of files, such as reports and log files, under the run_path: <project_name>/openlane/<design_name>/runs/<design_name>

• Openlane's ASIC flow ends with physical verification. This begins by streaming out the GDS followed by running DRC, LVS, and Antenna checks on the design.

• A final summary report is produced by default as <run-path>/reports/final_summary_report.csv, for more details about the contents of the report check this documentation.

• A final manufacturability report is produced by default as <run-path>/reports/manufacturability_report.csv, this report contains the magic DRC, the LVS, and the antenna violations summaries.

• The final GDS-II file can be found under <run-path>/results/final/gds and can be displayed using Klayout

• You can also examine the layout after each step (for planning, placement, cts, ...), we can load the step DEF file produced by any step into Klayout. For example, to examine the layout after floor-planning, do the following:

  • Copy the LEF file <run_path>/tmp/merged.lef into the the folder <run_path>/results/floorplan:
  • Invoke Klayout
  • Inside klayout: File ⇒ Import ⇒ DEF/LEF, then choose the def file inside the floorplan folder and make sure that the merged.lef file is used as well.

Generally, a testbench is used to make sure that a design is working before actually fabricating it since fabrication is an expensive process. When we write a testbench we want to make sure that the design is performing the correct functionality. A testbench in caravel user’s project is written as a c file and a verilog file. The c file is the one that has code to be executed on the management core, thus this file is the one controlling the signals sent to any peripheral device in the user’s project area. The verilog file (or test bench) is used to simulate the management core and its interaction with the user project area.

Using the same test bench, there are 3 types of verification that can be performed summarized in the below table:

Returning back to the SPM example, here are the two files for the test bench, wb_port.c and wb_port.v. We defined the names of the 4 registers that were used by the SPM; reg_mprj_$lave_X, reg_mprj_$lave_Y, reg_mprj_$lave_P0 and reg_mprj_$lave_P1. Those names are going to be used as variable names in the c file. For example, if we write in c:

reg_mprj_$lave_X = 3
reg_mprj_$lave_Y = 10
if(reg_mprj_$lave_P0 == 30 && reg_mprj_$lave_P1==0)

This means: write 3 to the multiplicand register and write 10 to the multiplier register . Then read the product registers, if the product is equal to 30, do the statements following the if condition. Also, in the c file, there is a variable called reg_wb_enable, which must be set to 1 preceding any read or write operation. We also manipulate a variable called reg_mprj_datal, because this corresponds to the mprj_io[15:0] bits in the verilog test bench. We check the changes in the value stored on those bits to know if a successful multiplication operation has taken place.

Before running the test you need to do the following steps:

1. Replace the file wb_port.c under caravel_user_project/verilog/dv/wb_port with wb_port.c
   
2. Edit the file includes.rtl.caravel_user_project under caravel_user_project/verilog/includes and add the following lines:

-v $(USER_PROJECT_VERILOG)/rtl/user_proj_mul32.v
-v $(USER_PROJECT_VERILOG)/rtl/mul32.v
-v $(USER_PROJECT_VERILOG)/rtl/spm.v

3. Edit the file includes.gl.caravel_user_project under caravel_user_project/verilog/includes to replace user_proj_example.v to user_proj_mul32.v
   

Now you can run your tests on both rtl and gl using the following commands:

make verify-wb_port-rtl

make verify-wb_port-gl

NOTE: The rtl test can be simulated before you harden the design, the gl can only be simulated after hardening