Experimenting with OpenROAD for ECE 4750
==========================================================================

OpenROAD is an open-source electronic design automation toolflow that can
transform RTL into layout enabling quantitative area, energy, and timing
analysis. In this document, we walk through how to use OpenROAD to
analyze the area, energy, and timing of the fixed- and variable-latency
multipliers from Lab 1.

### Install OpenROAD Virtual Machine

We will work on installing OpenROAD on ecelinux, but in the meantime you
can use the OpenROAD virtual machine to experiment with the toolflow. Use
these instructions here:

 - <https://the-openroad-project.github.io/micro2022tutorial/content/0-prep.html>

USB 3.0 flash drives will be provided to students during the discussion
section, or students can also download the VirtualBox/UTM and the
corresponding VM from the links on the above page.

### Test the OpenROAD Toolflow

Open QTerminal inside the virtual machine. Then use the following to test
the OpenROAD toolflow:

 % cd $HOME/micro2022tutorial/OpenROAD-flow-scripts/flow
 % make

If the flow completes without error, congrats! You have pushed the GCD
unit through the flow to layout. You can look at the "Demo 1: Running the
Flow" section of this OpenROAD tutorial to learn more about what the tool
is doing.

You can see the gate-level netlist like this:

 % cd $HOME/micro2022tutorial/OpenROAD-flow-scripts/flow
 % less results/nangate45/gcd/base/6_final.v

You can use KLayout to look at the layout by doing this:

 % cd $HOME/micro2022tutorial/OpenROAD-flow-scripts/flow
 % make klayout_6_final.gds

### Generate Verilog for Multipliers

Now log into ecelinux using the remote access method of your choice. You
don't need to do this through the VM. Source the setup script and run
your tests. There is no sense pushing anything through the flow if it
doesn't work!

 % source setup-ece4750.sh
 % cd $HOME/ece4750
 % git clone git@github.com:cornell-ece4750/lab-groupXX
 % cd lab-groupXX
 % TOPDIR=$PWD

 % mkdir -p $TOPDIR/sim/build
 % cd $TOPDIR/sim/build
 % pytest ../lab1_imul/test/IntMulBase_test.py
 % pytest ../lab1_imul/test/IntMulAlt_test.py
 % ls *.v
 IntMulBase_noparam__pickled.v
 IntMulAlt_noparam__pickled.v

If you look in the two generated Verilog files you will see that PyMTL3
has "pickled" all of the included Verilog files into a single file which
can then be used to push through the toolflow. Let's also run a
simulation to record the cycles/transaction.

 % cd $TOPDIR/sim/build
 % ../lab1_imul/imul-sim --impl base --input small --stats
 % ../lab1_imul/imul-sim --impl alt  --input small --stats

### Setup Flow

Now we need to setup OpenROAD to push both multipliers through the
toolflow. From the terminal in the VM first create a design directory and
then copy the pickled Verilog file into the VM.

 % mkdir $HOME/micro2022tutorial/lab1-imul-base
 % cd $HOME/micro2022tutorial/lab1-imul-base
 % scp netid@ecelinux.ece.cornell.edu:~/ece4750/lab-groupXX/sim/build/IntMulBase_noparam__pickled.v

 % mkdir $HOME/micro2022tutorial/lab1-imul-alt
 % cd $HOME/micro2022tutorial/lab1-imul-alt
 % scp netid@ecelinux.ece.cornell.edu:~/ece4750/lab-groupXX/sim/build/IntMulAlt_noparam__pickled.v

Now for each design you need to create a config.mk and a constraint.sdc
file. Here is what the config.mk file should look like for the baseline
design:

  export DESIGN_NAME=IntMulBase_noparam
  export PLATFORM=sky130hd
  export VERILOG_FILES=../../lab1-imul-base/IntMulBase_noparam__pickled.v
  export SDC_FILE=../../lab1-imul-base/constraint.sdc

  export SYNTH_ARGS=
  export CORE_UTILIZATION=50
  export PLACE_DENSITY=0.90
  export CORE_ASPECT_RATIO=1
  export CORE_MARGIN=5.0

You can use nano to create this file like this:

 % cd $HOME/micro2022tutorial/lab1-imul-base
 % nano config.mk

Here is what the constraint.sdc file should look like for the baseline
design:

  current_design IntMulBase_noparam

  set clk_period 3.5
  set clk_port_name clk

  set clk_name core_clock
  set clk_io_pct 0.2
  set clk_port [get_ports $clk_port_name]
  create_clock -name $clk_name -period $clk_period $clk_port

  set non_clock_inputs [lsearch -inline -all -not -exact [all_inputs] $clk_port]

  set_input_delay  [expr $clk_period * $clk_io_pct] -clock $clk_name $non_clock_inputs
  set_output_delay [expr $clk_period * $clk_io_pct] -clock $clk_name [all_outputs]

You can copy the constraint.sdc file used in the GCD unit and then use
nano to edit the file like this:

 % cd $HOME/micro2022tutorial/lab1-imul-base
 % cp ../exercise2/constraint.sdc .
 % nano constraint.sdc

Do the same for the alternative design and edit both the config.mk and
the constraint.sdc files accordingly (i.e., change the DESIGN_NAME,
VERILOG_FILES, and current_design).

### Push Multipliers through Toolflow

To push the baseline design through the toolflow you need to add the
following to the flow Makefile:

DESIGN_CONFIG=../../lab1-imul-base/config.mk

You can do this using nano like this:

 % cd $HOME/micro2022tutorial/OpenROAD-flow-scripts/flow
 % nano Makefile

Now you can push the baseline multiplier through the flow:

 % cd $HOME/micro2022tutorial/OpenROAD-flow-scripts/flow
 % make

You can see the gate-level netlist like this:

 % cd $HOME/micro2022tutorial/OpenROAD-flow-scripts/flow
 % less results/sky130hd/IntMulBase_noparam/base/6_final.v

Let's look at the final layout. First, let's get a nicer KLayout layer
map.

 % wget https://www.csl.cornell.edu/courses/ece4750/klayout.lyp $HOME

Then open up KLayout to look at the layout by doing this:

 % cd $HOME/micro2022tutorial/OpenROAD-flow-scripts/flow
 % make klayout_6_final.gds

Use _File > Load Layer Properties_ to open the klayout.lyp file you just
downloaded. You can use the OpenROAD GUI to look at explore your design
like this:

 % cd $HOME/micro2022tutorial/OpenROAD-flow-scripts/flow
 % make gui_final

You can look at the area breakdowns here:

 % cd $HOME/micro2022tutorial/OpenROAD-flow-scripts/flow
 % grep "Chip area" reports/sky130hd/IntMulBase_noparam/base/synth_stat.txt

You can look at critical path and power breakdowns using the log file
here:

 % cd $HOME/micro2022tutorial/OpenROAD-flow-scripts/flow
 % less logs/sky130hd/IntMulBase_noparam/base/6_report.log

You can do the same thing for the alternative design by changing the
DESIGN_CONFIG variable in the Makefile:

DESIGN_CONFIG=../../lab1-imul-alt/config.mk