From 58b0132159cfac361417560fe7ea7c70082fdb96 Mon Sep 17 00:00:00 2001 From: tchilikov-semify Date: Mon, 7 Sep 2026 14:20:10 +0100 Subject: [PATCH] [proj] KMAC D1 sign-off Add the D1 design sign-off checklist for the KMAC and move it to D1 in the stage table. --- doc/proj/kmac.md | 64 ++++++++++++++++++++++++++++++++++++++++++++++ doc/proj/stages.md | 3 ++- 2 files changed, 66 insertions(+), 1 deletion(-) create mode 100644 doc/proj/kmac.md diff --git a/doc/proj/kmac.md b/doc/proj/kmac.md new file mode 100644 index 000000000..0ec43a8d5 --- /dev/null +++ b/doc/proj/kmac.md @@ -0,0 +1,64 @@ +# KMAC + +The KMAC in Mocha is imported from OpenTitan. +The documentation for the hardware IP block is located [in the vendored HW directory tree][block doc]. +Mocha instantiates it only to check the ROM contents at boot: masking is disabled and the register, key manager, EDN, life cycle and interrupt interfaces are unused; their inputs are tied off to their respective package default values and their outputs are left unconnected. +[One patch][keymgr edn patch] declares the sideload key and EDN types in `kmac_pkg` to drop the `keymgr_pkg` and `edn_pkg` dependencies; the logic is unchanged. + +The rest of this document contains the design checklist for the KMAC hardware IP block for the CHERI Mocha top. + +## Design sign-offs + +### D1 + +The KMAC used for D1 sign-off is the one imported from OpenTitan at revision [bf4a2b2][OpenTitan hash]. +The sign-off checklist items are described in the [D1 design sign-off checklist][D1 checklist]. +This sign-off is based on commit [b597321][d1-commit]. + +| Type | Item | Status | Note/Collaterals | +|---------------|----------------------------|--------|------------------| +| Documentation | SPEC_COMPLETED | Done | [KMAC specification][block doc]. +| Documentation | CSR_DEFINED | Done | [KMAC registers][registers]. +| RTL | CLKRST_CONNECTED | Done | Modules containing submodules checked: `kmac.sv`, `kmac_core.sv`, `kmac_app.sv`, `kmac_entropy.sv`, `kmac_errchk.sv`, `kmac_msgfifo.sv`, `kmac_staterd.sv`, `kmac_reg_top.sv`, `sha3.sv`, `sha3pad.sv`, `keccak_round.sv` and `keccak_2share.sv`. Modules without clocks and resets are confirmed to be purely combinational: `prim_sec_anchor_buf`, `prim_slicer`, `prim_subreg_ext`, `tlul_cmd_intg_chk` and `tlul_rsp_intg_gen`. +| RTL | IP_TOP | Done | This module is defined in `kmac.sv`. +| RTL | IP_INSTANTIABLE | Done | It is instantiated in top chip system. +| RTL | PHYSICAL_MACROS_DEFINED_80 | Done | No memory macros or analogue components. The FIFO depths are fixed. +| RTL | FUNC_IMPLEMENTED | Done | All functionality already implemented. Mocha exercises only the unmasked application interface path. +| RTL | ASSERT_KNOWN_ADDED | Done | Output assertions are [here][output asserts] and cover every output. +| Code Quality | LINT_SETUP | Done | Verilator lint target with `-Wall` in `kmac.core` and in the top. The hidden enum value and circular combinational logic warnings [are waived][lint waivers]; the unused clock and width warnings are waived [in the block][block waivers]. + +### D2 + +*Checklist to be defined — see [stages.md][design stages].* + +### D3 + +*Checklist to be defined — see [stages.md][design stages].* + +## Verification sign-offs + +### V1 + +*Not yet started — see [stages.md][verification stages].* + +### V2 + +*Checklist to be defined — see [stages.md][verification stages].* + +### V3 + +*Checklist to be defined — see [stages.md][verification stages].* + +[block doc]: ../../hw/vendor/lowrisc_ip/ip/kmac/README.md +[missing asserts]: https://github.com/lowRISC/mocha/issues/707 +[design stages]: stages.md#design-stages +[verification stages]: stages.md#verification-stages +[OpenTitan hash]: https://github.com/lowRISC/opentitan/tree/bf4a2b24e41742151cfce9c4041e959a3ba76ca3 +[D1 checklist]: stages.md#d1-design-sign-off-checklist +[d1-commit]: https://github.com/lowRISC/mocha/commit/b5973217f704923917e7761f73df7dfcb8d0c345 +[registers]: ../../hw/vendor/lowrisc_ip/ip/kmac/doc/registers.md +[output asserts]: ../../hw/vendor/lowrisc_ip/ip/kmac/rtl/kmac.sv#L1531-L1541 +[ot checklist]: ../../hw/vendor/lowrisc_ip/ip/kmac/doc/checklist.md +[lint waivers]: ../../hw/top_chip/lint/top_chip_system.vlt +[block waivers]: ../../hw/vendor/lowrisc_ip/ip/kmac/lint/kmac.vlt +[keymgr edn patch]: ../../hw/vendor/patches/lowrisc_ip/kmac/0001-Remove-keymgr-edn-deps.patch diff --git a/doc/proj/stages.md b/doc/proj/stages.md index 644daf405..94b548bb5 100644 --- a/doc/proj/stages.md +++ b/doc/proj/stages.md @@ -19,7 +19,7 @@ This table shows the current design and verification stage for each block in Moc | Entropy source | D0 | V0 | | GPIO | D0 | V0 | | I2C | D0 | V0 | -| KMAC | D0 | V0 | +| [KMAC][] | D1 | V0 | | Mailbox | D0 | V0 | | PLIC | D0 | V0 | | Power manager | D0 | V0 | @@ -35,6 +35,7 @@ This table shows the current design and verification stage for each block in Moc | | | | | Top chip | N/A* | V0 | +[KMAC]: kmac.md [TileLink crossbar]: xbar_peri.md [UART]: uart.md