Yosys+Odin

[sdamghan]

Description

This PR adds the functionality of using Odin's technology mapping for a Yosys generated BLIF file in coarse grain format. Basically, the feature is added according to the following flow:

1. Yosys: A hardware design will be given to Yosys. Using the commands mentioned in synth.tcl script, Yosys generates a coarsen (not exploded into low-level logic) BLIF file. Technically, the generated BLIF file should have Yosys logic cells. such as $and, $logic_and, $add, $sub, $div, $pow, $mul, $mem and etc.

2. BLIF Reader: Odin-II is fed by the generated BLIF file as the main design. At this point, other options like architecture files can also be given to Odin-II as before.

3. BLIF Elaboration: The BLIF file will pass to the BLIF Elaboration phase, which basically, makes the netlist compatible with Odin-II's partial mapping. Worth noting to mention that some Yosys logic cells such as simple DFF or bitwise operations will be passed to the partial mapping phase intact. The first critical stage of the Yosys+Odin happens in the BLIF Elaboration phase since some logic cells like $pow, $div or $mul will be exploded into smaller components such as adders or shifters. Moreover, the block memories are being detected at this point; however, the hard-block mapping or memory-related optimization process will happen in the mid-phase between BLIF Elaboration and Partial mapping. The third phase for other logic cells, like logical nodes, will only include input/output ports reordering to make them compatible with the partial mapping structure.

   3.1. Optimization: This phase includes some optimization and decision-making concerning Odin-II's logic cells mapping and the given architecture. For instance, memory blocks generated by Yosys will be split into smaller pieces. Basically, a memory block generated by Yosys, excluding hard blocks such as SPRAM or DPRAM, is a whole memory cell that includes all reading and writing ports. As a result, not only this memory cell needs to be split into memory nodes compatible with Odin-II's partial mapping and available hard blocks, but also a few potential optimizations such as memory size or port size reductions are available at this point. Generally, Odin-II categorizes Yosys memory blocks in two: Read-Only Memory (ROM) and Block Memory (BRAM). ROMs will be mapped to SPRAM or DPRAM based on the number of reading ports. BRAMs, are mostly mapped to DPRAMs. Only if the read and the write address are equal, the BRAM will be mapped to SPRAM. Another potential optimization for memories here is to check the memory depth and see if it can fit into LUTRAMs. Some thresholds have been set based on the 6-LUTs specifications in Stratix IV and later; however, the LUTRAM inference in this tool is not one of those complicated ones. In addition to memories, adders will be modified at this stage if available adder hard blocks exist in the architecture file. Indeed, an adder node will be split into a chain of single-bit adders. Modifications like adding carry ports happen here as well.

4. Partial mapping: The fourth phase slightly changed from what partial mapping was in Odin-II previously. In this phase, Odin-II would partially map the netlist to low-level logic. The second essential phase is happening here since the given circuit to Yosys would utilize the available hard blocks in the VTR flow. These hard blocks are comprising of the available hard blocks in the given architecture to the Odin-II. Worth noting here that the primitive modules specified in the vtr_flow directory are given to Yosys as a library. That means users can also use VTR primitive components such as single_port_ram, dual_port_ram and adder as before. (Note: the infrastructure for this feature is completely implemented in Yosys+Odin. However, there is an issue with Yosys in which it does not generate these hard blocks with the user-defined size in the design file. The issue is filed in the Yosys repository link. The temporary solution for this issue is to paste the definition of these modules in the given design from vtr_flow/primitive.v).

Some notes worth mentioning:

• New supported designs in Odin-II:
  • Constant multiplication using shift operation.
  • Division and Modulo (constant and variable)
  • Exponentiation
  • Yosys synthesizable logic cells
• In this PR, the structure of Input and Output for Odin-II has changed as follow:
  • A GenericIO class, including GenericReaders and GenericWriters has been added.
  • Each GenericReader has the _read method, which is implemented based on the language structure. Currently, Odin-II only supports Verilog and BLIF as the input languages.
  • Similarly, each GenericWriter has the _write method to write into output file based on the specified language.
  • As a result of this new structure, the process of adding a new language to Odin-II would be much easier.
• A new getline method has been added to libvtrutil:
  • Yosys use to generates BLIF components in a single line, while Odin-II does vice versa.
  • As a result, Yosys BLIF reading and Odin-II BLIF reading differ from each other in terms of reading BLIF components.
  • To overcome this issue, a new method called getline is defined in libvtrutil.
  • Basically, this new method uses the C getdelim function to detects lines.
  • The getline method is compatible with Windows and Linux new lines
  • Also, it removes the comment part of an input BLIF line like vtr::fgets.
  • Odin-II uses a method called "getbline" to read a complete BLIF line based on the BLIF type.
• Some benchmarks carried syntax errors. To avoid Yosys failure, they have been modified and updated in this PR. The compatibility of VTR and Odin-II benchmarks with Yosys + Syntax errors #1830
• For coarse-grain netlist, an option --fflegalize is added to make all DFFs rising edge by adding inverters.

Instruction to use:

1. Specifying the elaborator in Odin-II command, then Yosys will be run inside Odin-II:

./odin_II 
             -V circuit_design 
             -a architecturee_file
             -o ODIN_OUTPUT_BLIF
             --elaborator yosys  
             --fflegalize
             ...

The coarse-grain BLIF file and Yosys output log will be created in the same directory where the Odin-II output BLIF file is going to be placed

2. Generate the BLIF file and then pass it to Odin-II
   2.1. Generating Yosys BLIF file using run_yosys.sh script, located in "ODIN_II/regression_test/tools/".
   • Single test file:
     ./run_yosys -V VERILOG_FILE
   • A task including multiple test files or a task list(suite)
     ./run_yosys -t TASK.YCFG or TASKLIST
     task.ycfg is like ordinary VTR task files; however, the user only needs to specify circuit_dir and circuit_list_add. In the end, this script creates a new directory with the task name at "/ODIN_II/regression_tests/benchmark/_BLIF/XXX" and puts all generated BLIF inside it.
     task.ycfg example:

      ########################
      # run yosys config
     ########################
     
     # setup the circuits
      circuits_dir=regression_test/benchmark/verilog/micro
     
      # circuits' name
      circuit_list_add=*.v
     

   Note: the support for include_circuits option is not yet implemented in run_yosys.sh script.
   2.2. Odin-II can be fed by Yosys generated BLIF file using the following command:

   ./odin_II 
            -b YOSYS_GENERATED_BLIF 
            -a architecturee_file
            -o ODIN_OUTPUT_BLIF
            --coarsen  --fflegalize
            ...
   

Note: the other options, such as passing architecture files, Odin-II XML config files, etc., are the same.

###Changed or New Results
Due to the changes in VTR benchmarks, the golden results for some benchmarks need to be changed. You would find the comparison between the baseline (current VTR master branch) and the modified (recent changes) golden results in the following table:

Task Name	Comparison File
vtr_reg_nightly_test1/power_extended_circuit_list	nightly_test1_power_extended_circuit_list_comparison.ods
vtr_reg_nightly_test3/complex_switch	nightly_test3_complex_switch_comparison.ods
vtr_reg_nightly_test3/vtr_reg_qor	nightly_test3_vtr_reg_qor_comparison.ods
vtr_reg_nightly_test3/vtr_reg_qor_chain	nightly_test3_vtr_reg_qor_chain_comparison.ods
vtr_reg_nightly_test3/qor_chain_depop	nightly_test3_qor_chain_depop_comparison.ods
vtr_reg_nightly_test3/qor_chain_predictor_off	nightly_test3_qor_chain_predictor_off_comparison.ods

Due to the changes in the ODIN_II/multiplier.cpp, the golden results for "nightly1/arithmetic_tasks/mult_const" benchmarks have changed. The comparison between the baseline (current VTR master branch) and the modified (recent changes) golden results in the following table:

Task Name	Comparison File
vtr_reg_nightly_test1/arithmetic_tasks/mult_const	nightly_test1_arithmetic_mult_const_comparison.ods

Also, the comparison between the Yosys+Odin-II and Odin-II golden results for VTR benchmarks, based on the vtr_qor_reg_chain configuration is as follows:

Task Name	Comparison File
vtr_reg_yosys_odin/vtr_benchmarks	Yosys+Odin_vs_Odin_VTR_reg_qor_chain.ods
vtr_reg_yosys_odin/vtr_benchmarks_with_50%_mult_reduced	Yosys+Odin_vs_Odin_VTR_reg_qor_chain_mult50.ods

Related Issue

#1830
#1831

Motivation and Context

Aim to use the Odin-II partial mapping stage, which performs hard logic inference and hard/soft trade-off decisions for such a tool as Yosys. The goal is to automate the decision between what to place in hard blocks or explode into gates. The current Yosys flow forces the user to decide the discrete circuit implementation manually. The approach taken by the synthesizer is to map all discrete components into an available hard block or to explode them when not available, not caring for the device capacity. Our goal is to improve device utilization and simplify the flow by automating this decision with architecture awareness.

How Has This Been Tested?

Odin-II and VTR benchmarks

Types of changes

• Bug fix (change which fixes an issue)
• New feature (change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My change requires a change to the documentation
• I have updated the documentation accordingly
• I have added tests to cover my changes
• All new and existing tests passed

[aman26kbm]

This is awesome. Thanks for working on this, Seyed. Liked and Subscribed :)

[sdamghan]

@mithro would you please add odin_tech_strong to Kokoro tests. I have provided config files.
The PR is also ready for your review as well. I also have the plan to add Yosys as a subtree to VTR in separate PR, I think this PR is quite big so far.

[mithro]

I've added the odin_tech_strong.cfg configuration.

[mithro]

[vaughnbetz]

Looks like the basic sanitize tests are failing in the vpr router. Not sure why and whether it is related to this change or not. Presumably some memory corruption is occurring in the router, but that may be an underlying issue that some change in the benchmarks has triggered?

[vaughnbetz]

Partial review so far (still working on it).
Generally looks good, but there are some places where:

1. More high-level comments (file scope) on how things fit together would be useful.
2. I think some long routines (e.g. FF) look fairly repetitive, so there's room for some refactoring and helper functions to reduce repeated code.
3. The overview of this PR in the conversation tab is very good. I think that should be turned into a .md document and put in the Odin II source tree, or (probably even better) added to readthedocs (web page for vtr documentation) under an OdinII developer tab or some such.

[vaughnbetz]

A few more suggestions.

[vaughnbetz]

Huge PR and a ton of work @sdamghan !
Adding @KennethKent as a reviewer in case he has time, as I am not very familiar with Odin II's internals.
My biggest comment is to make sure someone could figure out the yosys + OdinII partial mapping flow from a mix of high-level comments in the code and documents like the one you wrote in this PR (likely put in an OdinII document in the vtr documentation).
Other comments:

• Make sure you comment data structures and enums and defined constants; I find I can usually figure out a program if I can figure out its data.
• Make sure any assert that user input could trigger is instead an error message.
• There are some long routines and some similar routines (e.g. the FF routines). I think they could be refactored to be shorter with helper functions in some cases (the FF ones seem easiest / most clear).

[vaughnbetz]

@tangxifan : I suspect the routing failures on the sanitized build are related to your recent rr-graph refactoring ... do you agree? Any ideas?

[tangxifan]

@tangxifan : I suspect the routing failures on the sanitized build are related to your recent rr-graph refactoring ... do you agree? Any ideas?

Yes. I agree. I think some new APIs do not manage memory allocation well. I am on it now. Sorry for the issue.

[mithro]

@QuantamHD - Can you take a look at this?

[QuantamHD]

@vaughnbetz I manually cancelled the job. You should be able to rerun by applying the kokoro:force-run label

[sdamghan]

@vaughnbetz I manually cancelled the job. You should be able to rerun by applying the kokoro:force-run label

Thanks @QuantamHD

[sdamghan]

@vaughnbetz modified benchmarks are merged into the VTR source tree, and duplicates are removed. Also, the include feature is now available for Yosys+Odin. I generated new QoR results and put them in a few tables in the PR description. Once @QuantamHD adds the new Kokoro runner for vtr_reg_yosys_odin (issue #1832), the PR is ready to merge unless there are more comments. When you find the time, would you mind letting me know your thoughts about the QoRs and PR?

[vaughnbetz]

Merged in a golden result change to an unrelated regtest QoR change on the master. CI just kicked off again due to that.

[vaughnbetz]

Hopefully that regtest passes within the QoR bounds; if not I'll try choosing the QoR data from this PR instead in the merge. It's the routing predictor off run, which tends to be noisy in cpu time.

[sdamghan]

@vaughnbetz sounds good; please let me know if you would need further changes

[vaughnbetz]

Committed an update to mcml's output count for vtr_reg_qor_chain_predictor_off's golden results. If this passes CI, will merge.

[vaughnbetz]

Waiting for OdinII basic and Vtr nightly tests 2. (1 day so far -- hung?)

[sdamghan]

@vaughnbetz Odin-II basic tests are already passed:

The GitHub action for Odin-II basic test has been renamed here; however, the CI still shows the previous name. There is no even a Details button to its status.

If the CI tag remains after merging this PR to the master branch, I will follow up on that.

It seems VTR nightly test 2 is hung; either we need to wait for it to meet the 72 hours timeout, or someone from the Google side could terminate it.

[vaughnbetz]

Thanks @sdamghan . Merged. If you can watch/confirm that the Odin II basic test rename is all working fine in PRs that would be great; I'm assuming it showing up here is spurious and will go away after the merge.

[sdamghan]

Thanks @vaughnbetz , I will definitely track the Odin-II CI tests