VPR: Add options for writing machine readable summary files

[lpawelcz]

Description

This PR adds 2 new options:

• --write_block_usage
• --write_timing_summary
  which enable VPR to write two summary files in JSON format.
  The first one reports the usage of specific blocks of given architecture for implemented design during packing step in format:

{
  "num_nets": "<int>",
  "num_blocks": "<int>",
  "input_pins": "<int>",
  "output_pins": "<int>",
  "blocks": {
    "<block_type_name_0>": <int>,
    "<block_type_name_1>": <int>,
    ...
    "<block_type_name_n>": <int>
  }
}

Second option writes final timing summary for the design evaluated in routing step. It consist of Critical Path Delay (cpd), Max Circuit Frequency (Fmax), setup Worst Negative Slack (sWNS), setup Total Negative Slack (sTNS). The format is as follows:

{
  "cpd": <double>,
  "fmax": <double>,
  "swns": <double>,
  "stns": <double>
}

Related Issue

This feature was suggested in #1944

Motivation and Context

Information provided in generated JSON files is used in SymbiFlow to perform tests that verify the block usage and timings against reference values in order to catch possible regression.
Current way of getting the information from VPR requires parsing the log output in search of timing summary and block usage info. It would be better solution to let VPR prepare the output in easy to read format so that we won't rely on log output that could be changed in the future and cause failures in log parsers.

How Has This Been Tested?

This was tested locally by adding new options to calls to VPR in symbiflow and inspecting the resulting files.

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

[mithro]

@lpawelcz - VPR has generally used XML for all the other file formats, I think it would be better to stick with that file format.

[acomodi]

LGTM, apart from a small typo.

@mithro regarding the XML vs JSON format, I believe that, for such cases, where the output structure is quite simple, JSON is a better fit.

As an alternative, we may enable to output both, based on the file extensions.

[lpawelcz]

New options now are able to select between XML and JSON formats based on the extension of the file passed with those options

[sfkhalid]

LGTM.

[mithro]

The new files formats should be documented in page at https://docs.verilogtorouting.org/en/latest/vpr/file_formats/ (which seems to be https://github.com/verilog-to-routing/vtr-verilog-to-routing/blob/master/doc/src/vpr/file_formats.rst ?).

[mithro]

Just two minor comments.

Please check the ReadTheDocs looks good.

Merge if @acomodi and @vaughnbetz are happy.

[lpawelcz]

Code blocks in docs were actually broken, sorry for that, they are OK now. Additionally, I noticed that I didn't update the command line options in docs when I added support for TXT files so I also fixed this.

[lpawelcz]

Hi @vaughnbetz, I think this one is ready. Please have a look at it and merge if there is nothing more to change here.

[vaughnbetz]

Looks good; just a few places where I suggest documenting that these are cluster-level netlist statistics. This can be merged and the commenting updated in another PR if you prefer.

[lpawelcz]

I updated docs, help message and text format as specified so another PR won't be needed.

[mkurc-ant]

Merging this one, Thanks everybody for reviews and comments.