diff --git a/doc/proj/stages.md b/doc/proj/stages.md index 82f45df9a..644daf405 100644 --- a/doc/proj/stages.md +++ b/doc/proj/stages.md @@ -10,7 +10,7 @@ Slight modification to the stages and checklists were made to meet the requireme This table shows the current design and verification stage for each block in Mocha. -| **Block name** | **Design stage** | **Verification stage** | +| **Module name** | **Design stage** | **Verification stage** | |-----------------------|------------------|------------------------| | AXI crossbar | D0 | V0 | | Clock manager | D0 | V0 | @@ -32,10 +32,15 @@ This table shows the current design and verification stage for each block in Moc | [TileLink crossbar][] | D1 | V1 | | Timer | D0 | V0 | | [UART][] | D1 | V1 | +| | | | +| Top chip | N/A* | V0 | [TileLink crossbar]: xbar_peri.md [UART]: uart.md +*The top chip integration has no design stage. +Its verification stages are defined separately in [Top-level chip verification](#top-level-chip-verification). + ## Sign-off procedure To advance a block from one stage to the next you must open a pull request with the checklist in a Markdown file called `doc/proj/BLOCK.md`, where `BLOCK` is replaced by the block's name. @@ -43,7 +48,7 @@ A [checklist template](checklist_template.md) is provided as a starting point. This pull request must be approved by at least three people, one of whom should ideally be someone who has not been involved in the design and the verification of the block. It should also update [the table](#current-status) documenting the current status of each block. -## Design stages +## Hardware IP block design stages These are the stages each block goes through. @@ -73,7 +78,7 @@ Checklists for signing off a block at D1. *D2 and D3 checklists to be added.* -## Verification stages +## Hardware IP block verification stages These are the verification stages each block goes through. Some items are marked as only for *simulation* or only for *formal* depending on which approaches are used in the verification process. @@ -109,3 +114,119 @@ Checklist for signing off a block at V1. | FPV_REGRESSION_SETUP | *Formal* | An FPV regression has been set up and added to `top_chip_fpv_ip_cfgs.hjson` | *V2 and V3 checklists to be added.* + +## Top-level chip verification + +These stages apply to the `top_chip` integration testbench. +The two key documents governing chip-level verification are: + +- **Verification plan** (primary): `hw/top_chip/dv/data/top_mocha_vplan.hjson` (still being written) - defines the coverage metrics and their mapping to tests. +- **Testplan**: `hw/top_chip/data/chip_testplan.hjson` (still being written) - captures individual testpoints and their associated tests. + +Both documents must be kept consistent as milestones progress. + +Two standing constraints apply throughout all chip-level milestones: +- **IP floor:** all integrated IP blocks must have reached the corresponding IP verification stage (V1 for chip V1, and so on). Blocks below the floor require a written waiver signed off by the DV lead. +- **Dual firmware mode:** both vanilla (non-CHERI) and CHERI firmware images must pass all applicable tests. A milestone is not met if only one mode passes. + +### What top-level tests cover + +Top-level tests target integration paths that cannot be observed in any individual IP testbench: + +- **Pin connectivity:** IP outputs reach the correct chip pins and external stimulus on input pins is correctly delivered to the right IP. +- **Interrupt routing:** each IP's interrupt signal propagates through the PLIC and arrives as a trap at the CPU. This path crosses multiple IPs and is untestable below the chip level. +- **Cross-IP data paths:** data flowing between two or more IPs - for example the ROM controller using the KMAC application interface at boot, or the alert handler forwarding escalation to the reset manager. +- **Clock and reset distribution:** the reset tree and clock gating logic correctly propagate resets and enable/disable clocks across the chip. +- **Boot sequence:** the ROM controller runs its startup routine, passes the integrity check, and transfers execution to the SRAM image before the CPU runs any firmware. +- **CPU integration:** the CPU core is correctly wired into the memory subsystem, interrupt infrastructure, and debug module. End-to-end tests exercise the full path from a firmware action (instruction fetch, memory access, trap) through the chip fabric and back, confirming the CPU's bus transactions, interrupt acknowledgements, and exception handling are correctly handled by the surrounding logic. Examples include verifying that a memory access produces the expected transaction on the fabric, or that a store correctly updates state in a downstream controller (e.g. setting a tag bit) and a subsequent access reflects that change. + +### What top-level tests do not cover + +Top-level tests intentionally do not re-verify IP-internal behaviour: + +- **CSR correctness:** register reset values, read/write semantics, bit-bash - verified at block level. +- **Protocol compliance:** SPI timing, I2C ACK/NACK handling, UART framing - verified at block level. +- **Error injection and recovery within an IP:** verified at block level. +- **Functional coverage of individual IP RTL:** tracked and closed at block level. + +A test that could pass or fail based solely on IP-internal behaviour, with no observable effect at the chip level, does not belong in the chip-level testplan. + +### Chip-level stage definitions + +| **Stage** | **Name** | **Definition** | +|-----------|----------|----------------| +| V0 | Initial Work | | +| V1 | Smoke Passing | | +| V2 | Integration Complete | | +| V3 | Verification Complete | | + +### Smoke test expectations + +A chip-level smoke test verifies one IP at a time and must demonstrate two things: + +1. **Register reachability:** SW writes and reads at least one CSR, confirming correct address-map wiring through the crossbar. +2. **One integration-unique functional path:** one transaction that exercises a path only present at the chip level. The chip's external ports relevant to the IP under test must be connected to a UVM agent or a component that actively drives or passively observes them; a port left undriven or tied off does not count as exercised. This distinguishes a chip-level smoke from an IP-level smoke. + +Smoke tests must be short and deterministic. A smoke test that fails only because of an IP-internal bug (not a wiring or routing bug) indicates the IP has not yet reached its own V1 milestone and should not be blocking chip V1. + +### Smoke regression + +The V1 smoke regression is the set of tests that gate chip V1: the per-IP smoke tests above, plus a few cross-cutting chip-level checks that do not belong to any single IP. + +Interrupt routing is one such check. As a suggestion, rather than testing an interrupt inside each per-IP smoke, a single consolidated test forces every interrupt source via its `INTR_TEST` register and confirms end-to-end delivery to the CPU. This routing check is a V1 requirement; richer interrupt behaviour (priorities, preemption, real-event triggering) is post-V1. + +### Top-level V1 sign-off checklist + +| **Item name** | **Description** | +|---------------|-----------------| +| TOP_DV_DOC_DRAFTED | DV document drafted covering testbench architecture, agent topology, firmware-driven stimulus model, and chip-level coverage intent. | +| TOP_VPLAN_REVIEWED | Verification plan (`top_mocha_vplan.hjson`) substantively complete: every planned coverage item has a metric-to-test mapping and its milestone specified, with no known major coverage gaps. Reviewed with stakeholders across DV, design and software/firmware so no perspective's coverage gaps or methodological misalignments remain before DV execution begins. The plan is expected to evolve as the design matures. | +| TOP_TESTPLAN_REVIEWED | Chip-level testplan (`chip_testplan.hjson`) substantively complete: at least one testpoint per integrated IP and no known major testpoint gaps. Reviewed with stakeholders across DV, design and software/firmware so no perspective's testpoint gaps remain before DV execution begins. The plan is expected to evolve as the design matures. | +| TOP_TB_COMPLETED | Top-level testbench instantiates the DUT with all chip interfaces connected to a UVM agent, an interface or a module that can actively drive or passively observe them. Tie-offs are only permitted for interfaces that are architecturally unused; each must be documented with justification. Exceptions require a written waiver signed off by the DV lead. | +| TOP_BOOT_INFRA_PASSING | The SW-to-DV pass/fail signalling mechanism is confirmed working before any other firmware-driven test result is trusted. | +| TOP_ALL_TESTS_PASSING_V1 | All V1 testpoints in the testplan passing. | +| TOP_VPLAN_COVERAGE_V1 | All V1 items defined in the verification plan achieved. | +| TOP_INTERRUPT_ROUTING | Machine-mode delivery to the CPU confirmed for every interrupt-capable IP by one or multiple routing tests. | +| TOP_SMOKE_REGRESSION_IN_CI | V1 smoke suite runs in the nightly regression. Per-PR CI gating is not required for V1 sign-off but is encouraged once the infrastructure supports it. | +| TOP_WEEKLY_REGRESSION | Full test suite runs on a regular schedule (weekly at minimum; nightly if the CI infrastructure already supports it). This is not a randomness exercise but a health check to detect regressions in non-smoke tests as RTL development progresses between PRs. | + +### Top-level V2 sign-off checklist + +**Note:** +*This checklist is a proposal, not a strict requirement.* +*Requirements may be refined based on experience gained during V1 and continued design evolution.* + +| **Item name** | **Description** | +|---------------|-----------------| +| TOP_DV_DOC_COMPLETED | DV document fully written including testbench architecture, agent topology, and checking strategy. | +| TOP_VPLAN_COMPLETED | Verification plan (`top_mocha_vplan.hjson`) finalized: all planned coverage items complete, gaps found during V1 execution closed, and any spec changes folded in. | +| TOP_TESTPLAN_COMPLETED | Chip-level testplan (`chip_testplan.hjson`) finalized: all planned testpoints complete, gaps found during V1 execution closed, and any spec changes folded in. | +| TOP_ALL_INTERFACES_EXERCISED | Every chip-level interface is connected to a UVM agent, or an interface or a module that actively drives or observes it, and exercised by at least one passing test. Tie-offs are only permitted for interfaces that are architecturally unused on this chip variant; each must be documented with justification. | +| TOP_INDEPENDENT_CHECKING | Where feasible at the chip level, test outcomes are independently confirmed by UVM scoreboards, protocol checkers, or assertions. SW-side pass/fail is accepted as the primary checking mechanism where independent observation is not practical. | +| TOP_INTERRUPT_ROUTING_FULL | Supervisor-mode delivery exercised for all applicable interrupt sources, and each interrupt triggered from a real hardware event (beyond the machine-mode `INTR_TEST` routing confirmed at V1). | +| TOP_CROSS_IP_PATHS | Cross-IP integration paths exercised, alert sources through alert handler to escalation and reset manager. | +| TOP_RESET_PATHS | Software reset, NDM reset via the debug module, and alert-escalation reset each exercised: correct reset cause register state confirmed after each. | +| TOP_ALL_TESTS_PASSING_V2 | All V1 and V2 testpoints in the testplan passing. | +| TOP_VPLAN_COVERAGE_V2 | All V1 and V2 items defined in the verification plan achieved. | +| TOP_GLUE_CODE_COVERAGE_90 | ≥90% line, branch, toggle and FSM code coverage on the top-level glue logic. IP blocks verified at block level are black-boxed; only the integration logic is in scope. | +| TOP_NO_HIGH_PRIORITY_ISSUES | All P0 and P1 bugs closed. | + +### Top-level V3 sign-off checklist + +**Note:** +*This checklist is a proposal, not a strict requirement.* +*Requirements may be refined based on experience gained during V1 and V2.* + +| **Item name** | **Description** | +|---------------|-----------------| +| TOP_DV_DOC_REVIEWED | DV document reviewed a final time and confirmed to match the as-built testbench architecture and checking strategy. | +| TOP_VPLAN_FINAL_REVIEWED | Verification plan reviewed and confirmed complete and consistent with the closed coverage. | +| TOP_TESTPLAN_FINAL_REVIEWED | Chip-level testplan reviewed and confirmed complete and consistent with the executed tests. | +| TOP_ALL_TESTS_PASSING_V3 | All testpoints passing; no regression on prior milestone tests. | +| TOP_VPLAN_COVERAGE_V3 | All items defined in the verification plan achieved. | +| TOP_GLUE_CODE_COVERAGE_100 | 100% line, branch, toggle and FSM code coverage on the top-level glue logic. IP blocks verified at block level are black-boxed; only the integration logic is in scope. Exclusions reviewed and justified. | +| TOP_XPROP_CLEAN | X-propagation enabled in simulation with no X sources in driven logic. | +| TOP_NO_TOOL_WARNINGS | No compile-time or run-time simulator warnings in passing regressions. | +| TOP_TB_LINT_COMPLETE | Testbench lint flow clean; all waiver files reviewed. | +| TOP_NO_TODOS | No TODO comments remaining in testbench code or testplan. | +| TOP_NO_ISSUES_PENDING | All bugs closed; no open issues against top-level DV or RTL. |