Alliance Check Toolkit

August 30, 2019

Katana is now used as the default router. It can now manage a complete chip design with I/O pads. As a consequence, the Makefile are all modificated, the variable USE_KATANA=Yes is changed to USE_KITE=No (see Benchmark Makefiles).

Designs with I/O pads are also modificated to be processed by Katana as it uses a different approach.

Coriolis Configuration Files

Unlike Alliance which is entirely configured through environement variables or system-wide configuration file, Coriolis uses configuration files in the current directory. They are present for each bench:

• <cwd>/coriolis2/__init__.py : Just to tell Python that this directory contains a module and be able to import it.
• <cwd>/coriolis2/settings.py : Override system configuration, and setup technology.

Coriolis and Clock Tree Generation

When Coriolis is used, it create a clock tree which modificate the original netlist. The new netlist, with a clock tree, has a postfix of _clocked.

rhel6 and Clones

Under rhel6 the developpement version of Coriolis needs the devtoolset-2. os.mk tries, based on uname to switch it on or off.

Yosys Wrapper Script yosys.py

As far as I understand, yosys do not allow it's scripts to be parametriseds. The yosys.py script is a simple wrapper around yosys that generate a custom tailored tcl script then call yosys itself. It can manage two input file formats, Verilog and rtlil and produce a blif netlist.

ego@home:VexRiscv/cmos350$ ../../../bin/yosys.py \
                                       --input-lang=Verilog  \
                                       --design=VexRiscv     \
                                       --top=VexRiscv        \
                                       --liberty=../../../cells/nsxlib/nsxlib.lib

Here is an example of generated tcl script: VexRiscv.ys:

set verilog_file VexRiscv.v
set verilog_top  VexRiscv
set liberty_file .../alliance-check-toolkit/cells/nsxlib/nsxlib.lib
yosys read_verilog          $verilog_file
yosys hierarchy -check -top $verilog_top
yosys synth            -top $verilog_top
yosys dfflibmap -liberty    $liberty_file
yosys abc       -liberty    $liberty_file
yosys clean
yosys write_blif VexRiscv.blif

alliance-run

This benchmark comes mostly with it's own rules and do not uses the ones supplieds by rules.mk. It uses only the top-level configuration variables.

It a sligtly modified copy of the alliance-run found in the Alliance package (modification are all in the Makefile). It build an am2901, but it is splitted in a control and an operative part (data-path). This is to also check the data-path features of Alliance.

And lastly, it provides a check for the Coriolis encapsulation of Alliance through Python wrappers. The support is still incomplete and should be used only by very experienced users. See the demo* rules.

am2901 standard cells

This benchmark can be run in loop to check slight variations. The clock tree generator modify the netlist trans-hierarchically then saves the new netlist. But, when there's a block without a clock (say an alu for instance) it is not modificated yet saved. So the vst file got rewritten. And while the netlist is rewritten in a deterministic way (from how it was parsed), it is not done the same way due to instance and terminal re-ordering. So, from run to run, we get identical netlists but different files inducing slight variations in how the design is placed and routed. We use this defect to generate deterministic series of random variation that helps check the router. All runs are saved in a ./runs sub-directory.

The script to perform a serie of run is ./doRun.sh.

To reset the serie to a specific run (for debug), you may use ./setRun.sh.

Checking Procedure

• DRC with druc.
• Formal proof between the layout and the behavioral description. This is a somewhat long chain of tools:
  1. cougar, extract the spice netlist (.spi).
  2. yagle, rebuild a behavioral description (.vhd) from the spice netlist.
  3. vasy, convert the .vhd into a .vbe (Alliance vhdl subset for behavioral descriptions).
  4. proof, perform the formal proof between the refence .vbe and the extracted one.

Synopsys Liberty .lib Generation

The generation of the liberty file is only half-automated. hitas / yagle build the base file, then we manually perform the two modifications (see below).

The rule to call to generate the liberty file is: <libname>-dot-lib where <libname> is the name of the library. To avoid erasing the previous one (and presumably hand patched), this rule create a <libname>.lib.new.

1. Run the ./bin/cellsArea.py script which will setup the areas of the cells (in square um). Work on <libname>.lib.new.

2. For the synchronous flip-flop, add the functional description to their timing descriptions:

   cell (sff1_x4) {
     pin (ck) {
       direction : input ;
       clock : true ;
       /* Timing informations ... */
     }
     pin (q) {
       direction : output ;
       function : "IQ" ;
       /* Timing informations ... */
     }
     ff(IQ,IQN) {
       next_state : "i" ;
       clocked_on : "ck" ;
     }
   }
   
   cell (sff2_x4) {
     pin (ck) {
       direction : input ;
       clock : true ;
       /* Timing informations ... */
     }
     pin (q) {
       direction : output ;
       function : "IQ" ;
       /* Timing informations ... */
     }
     ff(IQ,IQN) {
       next_state : "(cmd * i1) + (cmd' * i0)" ;
       clocked_on : "ck" ;
     }
   }
   

Helpers Scripts

tcl scripts for avt_shell related to cell validation and characterization, in ./benchs/bin, are:

• extractCell.tcl, read a spice file and generate a vhdl behavioral description (using yagle). This file needs to be processed further by vasy to become an Alliance behavioral file (vbe). It takes two arguments: the technology file and the cell spice file. Cell which name starts by sff will be treated as D flip-flop.
• buildLib.tcl, process all cells in a directory to buil a liberty file. Takes two arguments, the technology file and the name of the liberty file to generate. The collection of characterized cells will be determined by the .spi files found in the current directory.

Calling the Generator

A script ./check/generator.py must be written in order to call the generator in standalone mode. This script is quite straigthforward, what changes between generators is the command line options and the stratus.buildModel() call.

After the generator call, we get a netlist and placement, but it is not finished until it is routed with the Coriolis router.

Scaling the Cell Library

This operation has to be done once, when the cell library is initially ported. The result is put in the git repository, so there's no need to run it again on a provided library.

The script is ./check/scaleCell.py. It is very sensitive on the way the library pathes are set in .coriolis2/settings.py. It must have the target cell library setup as the WORKING_LIBRARY and the source cell library in the SYSTEM_LIBRARY. The technology must be set to the target one. And, of course, the script must be run the directory where .coriolis2/ is located.

The heart of the script is the scaleCell() function, which work on the original cell in variable sourceCell (argument) and scaledCell, the converted one. Although the script is configured to use the scaled technology, this do not affect the values of the coordinates of the cells we read, whatever their origin. This means that when we read the sourceCell, the coordinates of it's components keeps the value they have under SxLib. It is when we duplicate them into the scaledCell that we perform the scaling (i.e. multiply by two) and do whatever adjustments we need. So when we have an adjustment to do on a specific segment, say slihgtly shift a NDIF, the coordinates must be expressed as in SxLib (once more: before scaling).

The script contains a getDeltas() function which provide a table on how to resize some layers (width and extension).

As the scaling operations is very specific to each macro-block, this script is not shared, but customized for each one.

One script to run them all: go.sh

To call all the bench's Makefile sequentially and execute one or more rules on each, the small script utility go.sh is available. Here are some examples:

ego@home:bench$ ./bin/go.sh clean
ego@home:bench$ ./bin/go.sh lvx

Command Line cgt: doChip.py

As a alternative to cgt, the small helper script doChip.py allows to perform all the P&R tasks, on an stand-alone block or a whole chip.

Blif Netlist Converter

The blif2vst.py script convert a .blif netlist into an Alliance one (vst). This is a very straightforward encapsulation of Coriolis. It could have been included in doChip.py, but then the make rules would have been much more complicateds.

Pad Layout Converter px2mpx.py

The px2mpx.py script convert pad layout from the pxlib (Alliance dummy technology) into mpxlib (mosis compliant symbolic technology).

Basically it multiplies all the coordinate by two as the source technology is 1µ type and the target one a 2µ. In addition it performs some adjustement on the wire extension and minimal width and the blockage sizes.

As it is a one time script, it is heavily hardwired, so before using it do not forget to edit it to suit your needs.

The whole conversion process is quite tricky as we are cheating with the normal use of the software. The steps are as follow:

1. Using the Alliance dummy technology and in an empty directory, run the script. The layouts of the converted pads (*_mpx.ap) will be created.
2. In a second directory, this time configured for the mosis technology (see .coriolis2_techno.conf) copy the converted layouts. In addition to the layouts, this directory must also contain the behavioral description of the pads (.vbe). Otherwise, you will not be able to see the proper layout.
3. When you are satisfied with the new layout of the pads, you can copy them back in the official pad cell library.