[multitop] Tracking issue

@pamaury is already working on this.

Since Feb 4, 2025.

### Description

This issue track issues identified during the multitop work and that should be addressed in the future:

High priority:
- [ ] document devicetables: in `SUMMARY.md` and in Doxygen
- [x] Document `//hw/top` mechanism: [done](https://opentitan.org/book/hw/top/index.html)
- [x] Doxygen multitop: see #26753
- [ ] Document devicetables in /book/sw/ and point to DT
- [ ] Document dtgen: #27521
- [ ] Document top creation: #27354
- [ ] Cross-ref dtgen and top creation
- [ ] Improve multitop documentation, see #25721
- [ ] add a generic way to supporting per-top files such a linker files, see e.g. https://github.com/lowRISC/opentitan/pull/26038#discussion_r1940948885 This is already done for IPS, see https://github.com/lowRISC/opentitan/pull/26248/commits/e3db8214b1541c0b7a9c06a2b914d1be1c692085 and #26248 more generally
- [ ] find a better way to support per-top init code, such as in `test_rom_start.S`, see https://github.com/lowRISC/opentitan/pull/26038#discussion_r1941009139 and the testutils/test_rom more generally. Probably needs the previous item done first so we can have per-top libraries of helper functions.
- [x] Remove all hardcoded rstmgr constants, see [#26195](https://github.com/lowRISC/opentitan/issues/26195#issuecomment-2786156249)
- [ ] Restore english breakfast

Medium priority:
- [ ] add blzmod and out-of-tree support to `hw/top`, see https://github.com/lowRISC/opentitan/pull/25580#issuecomment-2546834568 Prototype in #26191
- [ ] make the build system more multitop aware: prototype work done by @pamaury , still far from complete
- [ ] fix `arch.{c,h}` to handle multitop, see e.g. https://github.com/lowRISC/opentitan/pull/26038#discussion_r1943348952
- [x] fix status code for DV #26335
- [ ] remove clock freq definitions when everything depends on the DT
- [ ] some DIF unittest don't run because they require `--//hw/top=darjeeling`. We need to make sure that every unittest runs on at least one top. Maybe figure out a better way to do that?

Low priority:
- [ ] we apparently do not have any test that makes sure that the mask ROM contains the `chip_info` data. Maybe we should create one.
- [ ] check if multireg name issue still exists, if so then fix reggen, see https://github.com/lowRISC/opentitan/pull/26038#discussion_r1943361774
- [ ] revisit the ROM scrambling script to avoid a hardcoded table, see https://github.com/lowRISC/opentitan/pull/26038#discussion_r1940323255 and #26332
- [ ] start thinking about to handle IPgen'ed IPs with several instances: how do we handle DIFs? different register layouts? different interrupts?
- [ ] Revisit DT IP extension mechanism, see #26133 for details
- [ ] `uart_init` is marked as `noinline` because some rv_dm tests want to set a breakpoint there. This potentially wastes some bytes in the binary. Instead, we could try to record "breakpoint" location in a note section. Suggestion by @luismarques is to use `breakpoint1: { __attribute__((section(".breakpoints"))) static void *bp = &&breakpoint1; }`

**Done**
- [x] Remove all hardcoded pwrmgr constants, done in #26441
- [x] document `hw/top` (done: #26328)
- [x] some pins are MIOs on EG but DIOs on DJ, like the gpios. We need to make the code aware of that and find a general mechanism to handle both in case where it makes sense. Update pinmux testutils done in #26504, users need to be converted
- [x] go through all code in DIFs/testutils/test_rom/silicon_creator and evaluate the use of top-specific names for the DT, e.g. `kDtUart0` or `kDtRstmgrAon`. See @a-will in https://github.com/lowRISC/opentitan/pull/26038#pullrequestreview-2591443706. Mostly done, we also have introduce a "first" entry in #26774