[ipgen,otp_ctrl] Change otp_ctrl to ipgen

[matutem]

This commit is similar to other ipgen conversions, but changes a few
extra things because it needs to change the generation of otp memory
images. It merges the following 32 individual commits:

• Fix OtpMemMap exception message
• Improve handling template parameters by ipgen
  • Add doc and avoid redundant declaration.
• Move otp_ctrl images and mmap hjson out of hw/ip
  • The files that are top-specific moved to hw/top_earlgrey/data/otp
  • Adjust lots of paths to match this change
  • Move otp_ctrl_img.c.tpl to util/design/data since it is generic
  • Move the documentation of otp image generation to util/design/README.md
• Add otp_ctrl ipgen tpldesc hjson file
• Copy all hw/ip/otp_ctrl files to ip_templates
  • This is a straight copy with no changes to the files.
• Remove generated files
  • There is no use for files in ip_templates that will end up being
    generated.
• Move template files to their specific directories
• Turn a few more files into templates and fix paths
  • The template files are almost identical to the previous ones, except
    • they use ${topname} instead of a specific name
    • consecutive '#' are escaped so they are not considered hugo comments;
      for example, ### is replaced by ${"###"}
    • text bracketed by CMDGEN is removed
  • Adjust some relative paths to account for the change in the file locations.
  • Use {self_dir} to simplify some paths: it points to the location of the hjson
    file used to process the contents of a given file.
  • Fix some incorrect links to docs.
• Move top-specific items out of otp_ctrl_pkg
  • Move top-specific and implementation items to otp_ctrl_top_specific_pkg.
  • Create separate core files for both packages.
  • Adjust multiple sv files to use the right package.
  • Remove unused lc_otp_token_{req,rsp}_t.
• Fix core files
  • Change most core file into templates, use instance_vlnv, and declare
    a virtual target.
  • Change otp_ctrl_sim_cfg.hjson into a template since it uses a template
    fusesoc core.
• Change templates to use plain dictionaries
  • In practice this just removes redundant config token.
• Block building template targets
  • Add otp_ctrl in hw/ip_templates/BUILD all_files.
  • Template files are only intended for code generation, so it makes
    no sense to use them to build targets.
• Remove gen_comment from templates
  • The comment regarding generation for ipgen artifacts will be dealt
    with uniformly in the PR that fixes [ipgen] Insert per-ip DO NOT EDIT comment #25444.
  • Remove gen_comment from the tpldesc file.
• Add code in OtpMemMap to support ipgen
  • Create packages for design.lib and design.mubi.
  • gen-flash-img depends on modules that import topgen modules so it
    needs to have topgen in sys.path. This was not needed for some reason,
    perhaps the introduction of packages ends up requiring it.
• Place darjeeling mmap and img files under hw/top_darjeeling
  • This is similar to the new placement of the corresponding earlgrey files.
  • Fix the copyright banner.
• Block generation of dif artifacts
  • These artifacts need to be placed under top-specific directories.
  • When the sw side is ready for that, change the flow to create the
    per top generated files in the right place.
• Create otp_ctrl with ipgen
  • Create both earlgrey and darjeeling otp_ctrl with topgen.py via ipgen.
  • As a side effect some random constants are changed, since there
    are more requests for random numbers in topgen.
• Make util/design/gen-otp-mmap.py compatible with otp_ctrl ipgen
  • This tool may become obsolete, but it is best to upgrade it per
    the ipgen flow.
  • Comment out dif generation, and add a TODO with an explicit issue.
• Add mmap_def argument in bazel's otp_image_consts
• Remove unnecessary otp link in md file
  • This avoids the confusion about which top to refer to.
• Generate otp_ctrl difs via ipgen
• Fix top level core files
• Fix BUILD files
  • Use ip_autogen path for otp_ctrl_c_regs.
  • Use ip_autogen path for rust artifacts.
  • Change a few hw BUILD files for ipgen changes.
  • Fix reference to data/otp_ctrl.hjson in BUILD.tpl.
• Fix image handling in dvsim sim.mk
• Fix hjson files
• Fix md files
  • Describe references to top-specific otp_ctrl as examples.
• Fix BLOCKFILE
• Fix documentation collateral
• Fix englishbreakfast build
  • Remove otp_ctrl from top_englishbreakfast because it is not instantiated,
    but keep otp_ctrl_pkg since it shows in types of unconnected ports.
• Remove obsolete otp-mmap check from ci
• Remove legacy files
• Update hw/ip/README.md file

Fixes #25019

[cfrantz]

LGTM.

[matutem]

CHANGE_AUTHORIZED: BLOCKFILE

[cfrantz]

CHANGE_AUTHORIZED: BLOCKFILE

[Razer6]

LGTM, thanks.

At this point, can we hold-off merging that until the full ipgen flow for otp_ctrl is available? We, downstream, have a custom otp_ctrl based on hw/ip/otp_ctrl. Since we are in a quite critical phase now, I want to avoid adding another thing to deal with, e.g., porting those changes to Darjeeling, which eventually look different when the ipgen version is available.

Please build the future PRs on top of this one. Then we can merge the ipgen version as a direct sequence of PRs (or a single one).

[pamaury]

Thanks @matutem
On surface this looks good to me but I'll take more time to review it details later.

[matutem]

CHANGE AUTHORIZED: BLOCKFILE
CHANGE AUTHORIZED: hw/top_earlgrey/data/top_earlgrey.hjson
CHANGE AUTHORIZED: hw/top_earlgrey/data/otp/otp_ctrl_img_creator_sw_cfg.hjson
CHANGE AUTHORIZED: hw/top_earlgrey/data/otp/otp_ctrl_img_dev.hjson
CHANGE AUTHORIZED: hw/top_earlgrey/data/otp/otp_ctrl_img_hw_cfg.hjson
CHANGE AUTHORIZED: hw/top_earlgrey/data/otp/otp_ctrl_img_prod.hjson
CHANGE AUTHORIZED: hw/top_earlgrey/data/otp/otp_ctrl_img_raw.hjson
CHANGE AUTHORIZED: hw/top_earlgrey/data/otp/otp_ctrl_img_rma.hjson
CHANGE AUTHORIZED: hw/top_earlgrey/data/otp/otp_ctrl_img_test_locked0.hjson
CHANGE AUTHORIZED: hw/top_earlgrey/data/otp/otp_ctrl_img_test_locked1.hjson
CHANGE AUTHORIZED: hw/top_earlgrey/data/otp/otp_ctrl_img_test_unlocked0.hjson
CHANGE AUTHORIZED: hw/top_earlgrey/data/otp/otp_ctrl_img_test_unlocked1.hjson
CHANGE AUTHORIZED: hw/top_earlgrey/data/otp/otp_ctrl_img_test_unlocked2.hjson
CHANGE AUTHORIZED: hw/top_earlgrey/data/otp/otp_ctrl_mmap.hjson
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/otp_ctrl/rtl/otp_ctrl.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/otp_ctrl/rtl/otp_ctrl_core_reg_top.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/otp_ctrl/rtl/otp_ctrl_dai.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/otp_ctrl/rtl/otp_ctrl_ecc_reg.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/otp_ctrl/rtl/otp_ctrl_kdi.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/otp_ctrl/rtl/otp_ctrl_lci.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/otp_ctrl/rtl/otp_ctrl_lfsr_timer.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/otp_ctrl/rtl/otp_ctrl_part_buf.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/otp_ctrl/rtl/otp_ctrl_part_unbuf.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/otp_ctrl/rtl/otp_ctrl_pkg.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/otp_ctrl/rtl/otp_ctrl_prim_reg_top.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/otp_ctrl/rtl/otp_ctrl_reg_pkg.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/otp_ctrl/rtl/otp_ctrl_scrmbl.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/otp_ctrl/rtl/otp_ctrl_token_const.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/otp_ctrl/rtl/otp_ctrl_part_pkg.sv
CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/otp_ctrl/rtl/otp_ctrl_top_specific_pkg.sv
CHANGE AUTHORIZED: hw/top_darjeeling/ip_autogen/otp_ctrl/rtl/otp_ctrl.sv
CHANGE AUTHORIZED: hw/top_darjeeling/ip_autogen/otp_ctrl/rtl/otp_ctrl_core_reg_top.sv
CHANGE AUTHORIZED: hw/top_darjeeling/ip_autogen/otp_ctrl/rtl/otp_ctrl_dai.sv
CHANGE AUTHORIZED: hw/top_darjeeling/ip_autogen/otp_ctrl/rtl/otp_ctrl_ecc_reg.sv
CHANGE AUTHORIZED: hw/top_darjeeling/ip_autogen/otp_ctrl/rtl/otp_ctrl_kdi.sv
CHANGE AUTHORIZED: hw/top_darjeeling/ip_autogen/otp_ctrl/rtl/otp_ctrl_lci.sv
CHANGE AUTHORIZED: hw/top_darjeeling/ip_autogen/otp_ctrl/rtl/otp_ctrl_lfsr_timer.sv
CHANGE AUTHORIZED: hw/top_darjeeling/ip_autogen/otp_ctrl/rtl/otp_ctrl_part_buf.sv
CHANGE AUTHORIZED: hw/top_darjeeling/ip_autogen/otp_ctrl/rtl/otp_ctrl_part_pkg.sv
CHANGE AUTHORIZED: hw/top_darjeeling/ip_autogen/otp_ctrl/rtl/otp_ctrl_part_unbuf.sv
CHANGE AUTHORIZED: hw/top_darjeeling/ip_autogen/otp_ctrl/rtl/otp_ctrl_pkg.sv
CHANGE AUTHORIZED: hw/top_darjeeling/ip_autogen/otp_ctrl/rtl/otp_ctrl_prim_reg_top.sv
CHANGE AUTHORIZED: hw/top_darjeeling/ip_autogen/otp_ctrl/rtl/otp_ctrl_reg_pkg.sv
CHANGE AUTHORIZED: hw/top_darjeeling/ip_autogen/otp_ctrl/rtl/otp_ctrl_scrmbl.sv
CHANGE AUTHORIZED: hw/top_darjeeling/ip_autogen/otp_ctrl/rtl/otp_ctrl_token_const.sv
CHANGE AUTHORIZED: hw/top_darjeeling/ip_autogen/otp_ctrl/rtl/otp_ctrl_top_specific_pkg.sv

[matutem]

@andreaskurth I am not quite sure how to deal with the change checks: I created the list of authorized changes, but that doesn't prevent the check to fail due to too many files. From what I see, check-pr-changes-allowed.py script just helps generating the list of CHANGE AUTHORIZED.

[andreaskurth]

@matutem: We can run ci/scripts/check-pr-changes-allowed.py locally to confirm that all changes have been authorized as required. Only the following hasn't been authorized yet:

CHANGE AUTHORIZED: hw/top_earlgrey/ip_autogen/otp_ctrl/rtl/otp_ctrl_top_specific_pkg.sv

This is a new file to which top-specific (in this case for Earlgrey) otp_ctrl parameters and types have been moved. No functional change.

[matutem]

Yes @andreaskurth, the otp_ctrl_top_specific_pkg package has the items that were in otp_ctrl_pkg but that are top-specific.
By the way, this could be a useful split for other ipgens since it makes <ip>_pkg suitable for use by non-top-specific IPs, and can have the types used in top-level signals: we had to move some types around for other ipgen'ed IPs.

I take it your approval was with the understanding that these miscellaneous items would be handled adequately.

[a-will]

This hierarchy is wonky (not the fault of this PR; it's inherited and is similar to issues with flash_ctrl). An ipgen IP depends on the effectively virtual prim:otp, and that depends on the very same ipgen IP that instantiated it. In a world of multiple parameterizations, that doesn't work at all.

I feel like the OTP macro ought to live outside the otp_ctrl IP and instantiated in the "chip" level. Or...

Alternatively, perhaps we could have a template parameter for the OTP macro's (unique) module name and generate a generic macro with ipgen (instead of having a non-ipgen prim:otp). Stuff the generic macro we created in its own core file with a virtual VLNV. Then, otp_ctrl.core (and otp_ctrl.sv) could instantiate that module, instead of the non-ipgen prim_otp, and depend on the virtual VLNV. We'd essentially be creating a virtual macro library on the fly with ipgen, and top level core files would choose either the generated generic macro or an integrator's own.

Would that make sense to you?

[a-will]

On second thought, the "prim" CSR layout makes no sense to anyone but one particular integrator. Maybe that should become a top-specific, vendor-specific IP that gets instantiated at "chip" level. 🤔

[Razer6]

I guess both are a separate discussion. They do make sense but we firs should get otp_ctrl to ipgen and then iterate on that. Right now, this PR is gating to bringup Darjeeling on master.

[a-will]

I guess both are a separate discussion. They do make sense but we firs should get otp_ctrl to ipgen and then iterate on that. Right now, this PR is gating to bringup Darjeeling on master.

Oh, agreed on taking the incremental steps and not gating this PR on that particular issue. This was merely brought up for discussion.