need support for equivalence checking using .lib models

[Cronus-38]

Description

The equivalence checker built into Yosys, eqy, supports the use of .lib models. However, the ORFS flow currently only supports the use of verilog simulation models. This is problematic since it's not uncommon for simulation models for cells to be represented as UDPs, which are not supported by eqy. This makes the equivalence checking feature in ORFS unusable for many vendor libraries -- unless the user hacks the simulation models and replaces the UDP descriptions with synthesizable representations, but that's not really an acceptable solution.

Suggested Solution

To solve this, ORFS could provide a variable which controls what type of model is used for equivalence checking: verilog simulation models or eqy. This variable would be used to control branching logic in the write_eqy_script procedure in the load.tcl file. For example, the variable named EQUIVALENCE_CHECK_USE_LIBS could contain a list of .lib files to use, and the code could look like this:

proc write_eqy_script {} {
    set top_cell [current_design]
    set cell_files [get_verilog_cells_for_design]
    set outfile [open "$::env(OBJECTS_DIR)/4_eqy_test.eqy" w]

    # Gold netlist
    puts $outfile "\[gold]"
    if { [env_var_exists_and_non_empty EQUIVALENCE_CHECK_USE_LIBS] } {
        puts $outfile "read_liberty -ignore_miss_func $::env(EQUIVALENCE_CHECK_USE_LIBS)"
    } else {
        puts $outfile "read_verilog -sv $cell_files"
    }
    puts $outfile "read_verilog -sv $::env(RESULTS_DIR)/4_before_rsz.v \n"
    puts $outfile "prep -top $top_cell -flatten\nmemory_map\n\n"

    # Modified netlist
    puts $outfile "\[gate]"
    if { [env_var_exists_and_non_empty EQUIVALENCE_CHECK_USE_LIBS] } {
        puts $outfile "read_liberty -ignore_miss_func $::env(EQUIVALENCE_CHECK_USE_LIBS)"
    } else {
        puts $outfile "read_verilog -sv $cell_files"
    }
    puts $outfile "read_verilog -sv $::env(RESULTS_DIR)/4_after_rsz.v \n"
    puts $outfile "prep -top $top_cell -flatten\nmemory_map\n\n"
...

Additional Context

No response

[maliberty]

@povik any opinions?

[povik]

I think we can make the switch to always use the Liberty definitions and retire the Verilog models.

[maliberty]

@Cronus-38 do you want to make a PR?

[Cronus-38]

Sure, will do!

[Cronus-38]

@maliberty In order to capture the set of .lib files to be read into eqy, my thought is that the LIB_FILES variable would work nicely for single-corner builds, but if there are multiple corners (i.e. the CORNERS variable isn't empty) then I'm thinking the list of .lib files should be passed by creating a new environment variable as part of the read_liberty.tcl script (the relevant excerpt from the current version of read_liberty.tcl is pasted below). The write_eqy_script procedure would then read this new environment variable containing the full list of .lib files. I'm open to another solution if you have a better way in mind.

Side note: It probably isn't even necessary to read in .lib files from multiple corners since eqy is only interested in the function of each cell, but it would be safest to have eqy read everything rather than assuming every cell in the netlist exists in every corner.

#Read Liberty
if {[env_var_exists_and_non_empty CORNERS]} {
  # corners
  define_corners {*}$::env(CORNERS)
  foreach corner $::env(CORNERS) {
    set LIBKEY "[string toupper $corner]_LIB_FILES"
    foreach libFile $::env($LIBKEY) {
    read_liberty -corner $corner $libFile
    }
    unset LIBKEY
  }
  unset corner
} else {
  ## no corner
  foreach libFile $::env(LIB_FILES) {
    read_liberty $libFile
  }
}

[maliberty]

I don't see how you could meaningfully do timing with a cell only in some corners but not others. I think we should assume all cells exists in all corners (at least all used cells). I think it would suffice to pick an arbitrary corner.

[povik]

@Cronus-38 I'm curious, have you hit any roadblock with this?

[Cronus-38]

@povik My apologies -- I missed the notification email for your message back in June.

I wrote the code many weeks ago, but am only now preparing to create a PR. Are the instructions at the following link the procedure I should use?

https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts/blob/master/docs/user/FAQS.md

What is the branch naming convention?

[povik]

@Cronus-38 You should be free to choose any name for the branch. Regarding instructions on how to contribute please see the links below if they are helpful.

https://openroad-flow-scripts.readthedocs.io/en/latest/contrib/GettingInvolved.html
https://openroad-flow-scripts.readthedocs.io/en/latest/contrib/GitGuide.html

[Cronus-38]

@povik Thanks for the quick reply! In terms of adding a test, I'm not sure where I should put my test.sh script. The script will consist of some make commands which run the flow with various settings of the proposed EQUIVALENCE_CHECK_USE_LIBS variable.

[maliberty]

Is this a unit test or something users would use?

[Cronus-38]

The test.sh would just be a unit test.

[maliberty]

Then flow/test seems right