[pwrmgr,ipgen] Convert pwrmgr to ipgen

[matutem]

This has 16 commits, the first few are minor cleanups, and then

• the 4th creates the pwrmgr.tpldesc.hjson file under ip_templates/pwrmgr
• the 5th copies all pwrmgr files to ip_templates with no changes
• the 6th turns a few more files into templates
• the 7th changes topgen to render pwrmgr with ipgen, removes the old way to render it, and creates hw/top_earlgrey/ip_autogen/pwrmgr
• the 8th through the 14th fix markdown, BUILD, core, hjson, dif headers, verible allowlist, and documentation collateral in that order, so each is a focused small change
• the 15th removes the now obsolete files
• the 16th fixes the english breakfast build

Remember the ip_autogen files are generated, so they don't need much attention when reviewing.

Addresses #8440

[rswarbrick]

This is a reasonably big PR at the moment :-) Would it make sense to split out the first few commits into their own PR? We could get them in (and forget about them!) quickly while we think about the bigger changes that come later.

[matutem]

@rswarbrick I broke this PR into about 9 commits to address this issue. I think it is reasonable to commit this, since it addresses a 2 year old issue, and it has helped a lot in finding other areas of concern for multi-top, like the document generation, and make_new_dif. In other words, this doesn't address multi-top, but it will make it easier to deal with it.

[matutem]

@rswarbrick Regarding breaking this down into multiple PRs, the only sensible partition would be to have the first 5 commits into a PR, but they are almost trivial. The commits after that should go together. The interesting commits are

• commit 4, which creates the tpldesc hjson file and is pretty simple
• commit 6, which turns additional files into templates, which is really simple, except for escaping comments
• commit 7, which is just relatively simple changes in topgen.py and all other new files are generated
• commit 8, which is the most interesting commit, and it fixes various files (core, BUILD, and doc files mostly) to work with the autogen files; it also wipes out the now unused files, which is needed to avoid conflicting core files.

I added some of this info to each commit to help with per commit reviews.

[msfschaffner]

The kokoro issue should now be resolved #19853.

[rswarbrick]

Ok, thanks for the explanation. I'm afraid that I'm not enthusiastic about reviewing a 15-commit PR. I'm hoping there's some way to partition it into smaller pieces.

If it's honestly impossible to split it, I guess someone will have to review the whole lot at once. But I guess we'll also have to squash all the commits together to make the change atomic. I'm not sure I'm convinced that's the case: the current diff ~10,000 lines so you're not going to get any meaningful review (from anyone!) without some form of splitting.

[a-will]

I think it would help a lot if you reorganized the commits to do a move, instead of copy...delete. Most of the changes are from the copying (and another big chunk was the automatic lint fixes).

By the looks of it, though, after the change to a move, most of it would probably need to be squashed.

[hcallahan-lowrisc]

I didn't look too closely at the file copying/deleting commits or the autogeneration one (other than the topgen changes), but the rest of it look reasonable to me. Thanks for getting us one step closer to multi-top!

Regarding the commits, I think it's probably impossible to do all this in a simple, clean, atomic way. Maybe the copy+delete could be merged to make a single move commit that would be slightly cleaner. But I don't think it's critical.

[hcallahan-lowrisc]

It would nice to document the template parameters a bit further in the future. These descriptions are a little terse on their own, but maybe there could be links to a subsection in theory of operations about template parameterization that goes into a bit more depth. E.g. the difference between 'peripheral', 'int' and 'debug' indexes.

[matutem]

I tend to agree we need to describe parameterization. It should be a non-top-specific doc and location in the book, and the existing docs are generated, so end up top-specific. Perhaps pwrmgr/README.md.tpl is the most generic? I would punt this to another PR...

[hcallahan-lowrisc]

Yes let’s punt for now, it equally will apply to all ipgen blocks

[matutem]

@rswarbrick @a-will The reason I added specific comments and broke this into many commits, and highlighted in each commit what was the substantial change, is so you don't waste time looking at the creation or deletion steps. The effective number of lines changed in this commit is a whole lot less than 10,000.

This is a tricky PR. If I make it all in one commit (for atomicity), I may be asked again to break it into more commits. And if I change the commits to change the copy and delete step into a move there will be commits where nothing works.

I think the simplest way to really check this commit is to diff the files in ip_autogen against the union of the previous files in both ip/pwrmgr and the autogens in top_earlgrey/ip/pwrmgr. There should be very few minor differences. You will notice the absence of the "// Do NOT EDIT" comments. I think that can be handled in a separate commit. The reason is that now every single file in ip_autogen should have such notice, not just the ones created from templates. That change will also need to be retrofitted to alert_handler and rv_plic. I created #19943 for this.

[msfschaffner]

Thanks for the cleanup @matutem! This was long overdue.

[msfschaffner]

it is really nice to see these things disappear ;).

[msfschaffner]

CHANGE AUTHORIZED: hw/ip_templates/pwrmgr/rtl/pwrmgr.sv
CHANGE AUTHORIZED: hw/ip_templates/pwrmgr/rtl/pwrmgr_cdc.sv
CHANGE AUTHORIZED: hw/ip_templates/pwrmgr/rtl/pwrmgr_cdc_pulse.sv
CHANGE AUTHORIZED: hw/ip_templates/pwrmgr/rtl/pwrmgr_fsm.sv
CHANGE AUTHORIZED: hw/ip_templates/pwrmgr/rtl/pwrmgr_pkg.sv
CHANGE AUTHORIZED: hw/ip_templates/pwrmgr/rtl/pwrmgr_reg_pkg.sv
CHANGE AUTHORIZED: hw/ip_templates/pwrmgr/rtl/pwrmgr_reg_top.sv
CHANGE AUTHORIZED: hw/ip_templates/pwrmgr/rtl/pwrmgr_slow_fsm.sv
CHANGE AUTHORIZED: hw/ip_templates/pwrmgr/rtl/pwrmgr_wake_info.sv
CHANGE AUTHORIZED: hw/top_earlgrey/data/top_earlgrey.hjson
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/pwrmgr/rtl/pwrmgr.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/pwrmgr/rtl/pwrmgr_cdc.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/pwrmgr/rtl/pwrmgr_cdc_pulse.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/pwrmgr/rtl/pwrmgr_fsm.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/pwrmgr/rtl/pwrmgr_pkg.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/pwrmgr/rtl/pwrmgr_reg_pkg.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/pwrmgr/rtl/pwrmgr_reg_top.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/pwrmgr/rtl/pwrmgr_slow_fsm.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/pwrmgr/rtl/pwrmgr_wake_info.sv

[msfschaffner]

This needs another authorization to be merged.

[rswarbrick]

CHANGE AUTHORIZED: hw/ip_templates/pwrmgr/rtl/pwrmgr.sv
CHANGE AUTHORIZED: hw/ip_templates/pwrmgr/rtl/pwrmgr_cdc.sv
CHANGE AUTHORIZED: hw/ip_templates/pwrmgr/rtl/pwrmgr_cdc_pulse.sv
CHANGE AUTHORIZED: hw/ip_templates/pwrmgr/rtl/pwrmgr_fsm.sv
CHANGE AUTHORIZED: hw/ip_templates/pwrmgr/rtl/pwrmgr_pkg.sv
CHANGE AUTHORIZED: hw/ip_templates/pwrmgr/rtl/pwrmgr_reg_pkg.sv
CHANGE AUTHORIZED: hw/ip_templates/pwrmgr/rtl/pwrmgr_reg_top.sv
CHANGE AUTHORIZED: hw/ip_templates/pwrmgr/rtl/pwrmgr_slow_fsm.sv
CHANGE AUTHORIZED: hw/ip_templates/pwrmgr/rtl/pwrmgr_wake_info.sv
CHANGE AUTHORIZED: hw/top_earlgrey/data/top_earlgrey.hjson
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/pwrmgr/rtl/pwrmgr.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/pwrmgr/rtl/pwrmgr_cdc.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/pwrmgr/rtl/pwrmgr_cdc_pulse.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/pwrmgr/rtl/pwrmgr_fsm.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/pwrmgr/rtl/pwrmgr_pkg.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/pwrmgr/rtl/pwrmgr_reg_pkg.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/pwrmgr/rtl/pwrmgr_reg_top.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/pwrmgr/rtl/pwrmgr_slow_fsm.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/pwrmgr/rtl/pwrmgr_wake_info.sv