3. Quickstart guide

In this quickstart guide, we will illustrate core concepts of the project by translating a simple Verilog based design into a GDSII IC layout database using the freepdk45 virtual PDK.

3.1. Design

As a case study we will use the simple “heartbeat” design shown below. The heartbeat module is a free running counter that creates a single clock cycle pulse (“heartbeat”) every time the counter rolls over. Copy paste the code into your favorite text editor (vim, emacs, atom, notepad,etc) and save it to disk as “heartbeat.v”.

module heartbeat #(parameter N = 8)
   (
    //inputs
    input      clk,// clock
    input      nreset,//async active low reset
    output reg out //heartbeat
    );

   reg [N-1:0] counter_reg;

   always @ (posedge clk or negedge nreset)
     if(!nreset)
       begin
	  counter_reg <= 'b0;
	  out <= 1'b0;
       end
     else
       begin
	  counter_reg[N-1:0] <= counter_reg[N-1:0] + 1'b1;
	  out <= (counter_reg[N-1:0]=={(N){1'b1}});
       end

endmodule

To constrain the design, we need to also define a constraints file. Save the following snippet as heartbeat.sdc. If you are not familiar with timing constraints, don’t worry about it for now.

create_clock -name clk -period 10 [get_ports {clk}]

3.2. Setup

To address the complex process of modern hardware compilation, the SiliconCompiler schema includes over 300 parameters. For this simple example, we only need a small fraction of these parameters. The code snippet below illustrates the use of the Python API to set up and run a compilation. To run the example, copy paste the code into your text editor and save it to disk as “heartbeat.py”.

#!/usr/bin/env python3

import siliconcompiler                        # import python package

def main():
    chip = siliconcompiler.Chip('heartbeat')  # create chip object
    chip.input('heartbeat.v')                 # define list of source files
    chip.input('heartbeat.sdc')               # set constraints file
    chip.load_target("freepdk45_demo")        # load predefined target
    chip.run()                                # run compilation
    chip.summary()                            # print results summary
    chip.show()                               # show layout file

if __name__ == '__main__':
    main()

Much of the complexity of setting up a hardware compilation flow is abstracted away from the user through the load_target() function which sets up a large number of PDK, flow, and tool parameters based on a target setup module. To understand the complete target configuration, see the Flows directory, PDK directory, and Targets directory sections of the reference manual and read the source code for asicflow, freepdk45, and freepdk45_demo.

Note

The example assumes that Surelog, Yosys, OpenROAD, and KLayout are all correctly installed. Links to individual tool installation instructions and platform limitations can be found in the Tools directory.

It also requires downloading and pointing SC to FreePDK45, which is bundled with the SiliconCompiler repo. To install, clone the repo and set up an environment variable SCPATH pointing at the siliconcompiler/ directory inside of it:

git clone https://github.com/siliconcompiler/siliconcompiler
export SCPATH=$PWD/siliconcompiler/siliconcompiler

To simplify tool/PDK installation and job scheduling, SiliconCompiler supports a “-remote” option, which directs the compiler to send all steps to a remote server for processing. The “-remote” option relies on a credentials file located at ~/.sc/credentials on Linux or macOS, or at C:\\Users\\USERNAME\\.sc\\credentials on Windows.

Remote processing option is enabled by setting the ['option', 'remote'] parameter to True.

chip.set('option', 'remote', True)

3.3. Compilation

To compile the example, simply execute the ‘heartbeat.py’ program from your Python virtual environment.

python heartbeat.py

Alternatively, the simple heartbeat example can be run calling the SiliconCompiler ‘sc’ program directly from the command line.

#!/bin/bash

sc -design heartbeat \
   heartbeat.v \
   heartbeat.sdc \
   -target "freepdk45_demo"

If the compilation was successful, you should see a flood of tool specific information printed to the screen followed by a summary resembling the summary shown below. Set the ['option', 'quiet'] parameter to True of you want to redirect this information to a log file. By default, all SiliconCompiler outputs are placed in the build/<design> directory.

../_images/heartbeat_summary.png

3.4. View layout

If you have Klayout installed, you can view the output from the ‘asicflow’ by calling chip.show() from your Python program or by calling the sc-show program from the command line as shown below:

(venv) sc-show -design heartbeat
../_images/heartbeat.png