[top_darjeeling] DMI address shifting convention

Nobody has claimed this yet.

Commit 87d5764f brought rv_dm and lc_ctrl to be on the same xbar_dbg, which makes use of the existing TL-UL infrastructure. My recent PR #24758 returns the JTAG DPI interface back to the Darjeeling Verilator toplevel, but I noticed that accesses to the lc_ctrl part of the address space (starting at 0x20000) don't work; instead, they alias into rv_dm.

For example, the lifecycle state is located at 0x20038, but attempting to access that through `riscv dmi_read 0x20038` on OpenOCD returns *rv_dm's* [system bus access control and status register at 0x38](https://raw.githubusercontent.com/riscv/riscv-debug-spec/4e0bb0fc2d843473db2356623792c6b7603b94d4/riscv-debug-release.pdf#page=42) instead. This is because DMI accesses from JTAG get left-shifted by two before going into xbar_dbg...

https://github.com/lowRISC/opentitan/blob/2585f4a8cf61e3ccc4fe3565a7147e44ae9284ba/hw/ip/tlul/rtl/tlul_jtag_dtm.sv#L119

... and then truncated to 0x38, because the current `NumDmiByteAbits` parameter to tlul_jtag_dtm, at 18, isn't wide enough. The only reason accesses to rv_dm worked was because of a corresponding right shift in tlul_adapter_dmi:

https://github.com/lowRISC/opentitan/blob/2585f4a8cf61e3ccc4fe3565a7147e44ae9284ba/hw/ip/tlul/rtl/tlul_adapter_dmi.sv#L63-L64

Even if the number of DMI address bits were set correctly, it still wouldn't work because the corresponding right shift doesn't happen at lc_ctrl. In fact, a `riscv dmi_read 0x800e` (i.e. `0x20038 >> 2`) gets correctly routed to lc_ctrl and returns the lifecycle state correctly. It is relatively easy to replicate that address shift at lc_ctrl as done at rv_dm, but I think there is a broader issue I'd like feedback on:

As far as I can tell, the shifting is needed because the RISC-V Debug Module has word-size debug registers that are accessed at byte granularity. However, the existing TL-UL infrastructure expects word-aligned addresses for word-sized accesses in several places (e.g., tlul_adapter_dmi, tl_err, tlul_adapter_host). There are a few comments that obliquely note the requirement for word-aligned addresses, but don't make it clear it's because rv_dm's byte-addressed debug module registers need them. Addressing this issue sooner will help make for less surprising additions to the debug crossbar (especially now as I've seen increasing momentum in efforts to backport 87d5764f and other changes to master, e.g. #24507).

I see two ways forward: 1) make it an explicit convention that all DMI addresses are internally left-shifted by 2 before entering the TL-UL infrastructure, or 2) extend the TL-UL infrastructure to specially support DMI semantics (that is, full-word-size accesses on non-word-aligned addresses), and don't shift addresses anymore. Should it be the first, I think it would be worth calling this out more explicitly across the codebase and in documentation. And, of course, right-shifting addresses just before they get to lc_ctrl so that it functions properly. The second is more aesthetically appealing, but would call for pretty invasive changes to TL-UL.

Thanks for your consideration.

Start by tracing the address handling in hw/ip/tlul/rtl/tlul_jtag_dtm.sv and hw/ip/tlul/rtl/tlul_adapter_dmi.sv, then compare the rv_dm and lc_ctrl paths described in the issue. Review the two proposed DMI/TL-UL conventions and their documentation impact before choosing a direction. Done means the convention is explicit and lc_ctrl accesses such as 0x20038 work through the JTAG DMI path.

Written by the indexing model from the issue text.