more detailed Stat command

[suisseWalter]

On request of @phsauter I'm working on making stat more expressive.
The goal is to have more Information for unflattened designs.
Especially regarding area. It is already possible to use a "liberty" file that helps to estimate the area after the techmap step. where the designs normally aren't yet flattened. With this file it's already possible to get a good area estimates pre optimization. But with the current stat command the resulting report doesn't contain a lot of useful information.

In a later PR I will then also implement a way to get area estimates already before techmap.

A sample report can be found here: croc_chipexperiment.txt
A sample mock Liberty file can be found here : experiment_mock.lib.txt
For the format I took inspiration from: pulp-platform/croc#39. I haven't implemented all the data that is provided there.

This PR isn't yet final. Many parts of the code aren't in a clean state.
Regarding the generated report I'm looking for feedback on the following points:

• Is the naming of the columns clear?
• should I also do the hierarchical/local separation for wires/ports/memories/processes? We tend to yes.
• Should I include the the differentiation between combinatorial and sequential area? should it go everywhere or only in the design hierarchy? we tend to no.
• I started to differentiate between a cell and a instance, while in RTLIL everything is called a cell. For the user it makes a difference if something is a instance or a standard cell. If I keep this separation, what is a good way to do it? The current implementation depends on cells being in a lib file. Should it just be "all cells not defined in the design are stdcells" ?
  • with the current idea the problem would be, that if one doesn't provide a lib file everything becomes a instance. Is this acceptable?
• currently unknown area cells do not get propagated up. and the final report only includes the ones from the top-level module. Should it propagate everything up? We tend to a no, as instances also don't get propagated up.
• This doesn't yet have a json version. I will implement this as soon as everything else has been decided. As I assume that there are tools that are reading the json automatically, should there be a legacy mode for the json, such that these tools don't break? or should this be a new json mode with a different name, such that no scripts need to be changed?
• It would be relatively simple to have the module wise report in a hierarchical order. (having it in a reverse hierarchical order would be even simpler) should that be done over the current ID based ordering?

What are the reasons/motivation for this change?
We would like to have more detailed reporting of the area used by parts of the circuit.
Explain how this is achieved.
Parsing the modules hierarchically allows us to get the area of used modules.

If applicable, please suggest to reviewers how they can test the change.
To test this have a design after Techmap and not yet (completely) flattened.
Run stat stat -liberty <path/to/mock.lib> where mock.lib can be the lib file from above.

[widlarizer]

Hi, thanks for working on this. I like the general direction.

In a later PR I will then also implement a way to get area estimates already before techmap.

In terms of gate equivalents? Keep in mind that Yosys is not just an ASIC toolchain. Best not to assume the target is a CMOS chip, it might be a an FPGA, a SAT solver, or an academic coarse-grain reconfigurable accelerator

• The naming is verbose, I feel like "Area including submodules" "Count excluding submodules" would do just as well
• Yes, let's make it consistent between cells and other entities
• I don't have strong feelings about seeing sequential vs combinational but I think that sequential elements are rarely affected by small changes for which one wants to see results in stat, especially since abc doesn't usually touch your flops. Separating combinational out makes changes in it more visible, I suppose. I don't see why not to keep it
• The output should make it clear when an area and cell count is real. The presence of an unknown module without liberty file coverage shouldn't break stat, but recursively everything including it in the module hierarchy should then be clearly marked for uncertainty in cell count and area as well if applicable. Unknown modules should show up as if they were cells as they're leaf nodes just like cells. Internal cells should behave the same way (invalidate submodules-included numbers throughout the hierarchy, contribute to cell counts)
• Yes, let's keep a legacy json mode unless it's convenient to extend the current json output such that there's just extra values in the json tree, which I guess isn't the case
• Sure, hierarchically ordering the modules would be best. Don't leave out modules outside the hierarchy

Additionally,

• Without any area data there's no reason to print columns for area
• Please prefer rebasing on top of main to keep the PR clean

[suisseWalter]

In a later PR I will then also implement a way to get area estimates already before techmap.

In terms of gate equivalents? Keep in mind that Yosys is not just an ASIC toolchain. Best not to assume the target is a CMOS chip, it might be a an FPGA, a SAT solver, or an academic coarse-grain reconfigurable accelerator

The goal is to have a file to describe the "area" of the cells. Similar to the liberty files used currently by stat. This way people can write their own description of "area". I'm open to discuss this also on slack(cwalter_at_ethz.ch), as it isn't the primary goal of this PR.

Thanks for the feedback. I will implement it.

The naming is verbose, I feel like "Area including submodules" "Count excluding submodules" would do just as well

I currently use the word "Instances" to describe what you call submodules. Is submodules the prefered yosys naming and should I therefore switch over to using it everywhere?

[widlarizer]

It's not yosys naming, but consider the hierarchy foo/bar/baz. If you look at stat and it says "baz: area including instances" then it may seem like it's referring to instances of baz, rather than instances in baz. I'm not sure how exactly to word it, I don't like introducing new terms but "submodule" at least seems unambiguous. I'm definitely open to alternate ideas

[widlarizer]

We discussed this at the dev jour fixe (this is an event open to contributors here every Monday at 3PM central european time, feel free to pop in) and have reached some consensus for how we'd like to see this play out.

• Whenever possible the output should fit within 80 columns, as is yosys convention. This requires minimizing whitespace within reasonable bounds
• Hierarchical summary shouldn't have unused zeroed "local" columns
• The default view should match the current functionality, meaning no "hierarchical" columns. This will help keep it concise. The user story you're serving is "I'm synthesizing an ASIC and want to see where my area is coming from so that I can make it smaller". However, a common user story is "My synthesis flow targeting anything is creating this type of cell and I would like to see which pass created it". For this you don't care about including instances
• The "hierarchical" columns should then be hidden behind an option
• We agreed on "submodule" being nicely unambiguous but are definitely open to anybody chiming in with what terminology other tools may use in such circumstances
• The new functionality should have a matching json output mode to deter users from parsing the human-readable version

A possible way of formatting to reduce total output width at the cost of line count is this:

cell count
| area
| |

rather than

+------ cell count
| +---- area
||