`rtl/duck_cache_pkg.sv` — Cache/Coherency Types Reference (docs-only)

Simplified coherency type definitions for the 2-master MOESI integration: address/data widths, L2 geometry constants, and the MOESI state + agent-ID enums. Not imported by duck_coherency_ctrl.sv (or any other RTL module) — that file uses flat signals for Icarus Verilog 11 / cocotb 2.0 compatibility, matching this repo's existing RTL style. This file exists as a reference/documentation artifact only.

Where it fits

Not instantiated or imported anywhere. Read this file (or this page) as the canonical description of the MOESI states and constraints duck_coherency_ctrl.sv implements with flat logic signals instead of this package's typedef enums.

Constants

Parameter	Value	Meaning
`ADDR_WIDTH`	32	Physical address width
`DATA_WIDTH`	32	Data word width (1 word/cycle on the DRAM bus)
`LINE_WORDS`	8	Words per cache line
`LINE_BYTES`	32	`LINE_WORDS × 4`
`CACHELINE_BITS`	256	`LINE_WORDS × DATA_WIDTH`
`L2_SETS`	16	Number of sets
`L2_WAYS`	4	Ways per set
`L2_SIZE_B`	2048	`L2_SETS × L2_WAYS × LINE_BYTES`
`TAG_BITS` / `SET_BITS` / `WORD_BITS`	23 / 4 / 3	Address field widths

MOESI state enum

State	Encoding	Meaning
`INVALID`	`3'b000`	No valid copy
`SHARED`	`3'b001`	Clean, possibly shared
`EXCLUSIVE`	`3'b010`	Clean, sole owner
`OWNED`	`3'b011`	Dirty, but must supply data to sharers (not implemented — see below)
`MODIFIED`	`3'b100`	Dirty, sole owner

Agent IDs

ID	Encoding
`AGENT_CPU`	`1'b0`
`AGENT_NPU`	`1'b1`

Simplified 2-master transitions (as documented, for reference)

CPU read: CPU I → E (no sharers) or I → S (NPU holds a shared copy); NPU M → O if it must supply data.
CPU write: CPU * → M; NPU S/E/O/M → I (invalidated).
NPU DMA read: CPU M → O (flush dirty line, remain owner) or E/S/I → S; NPU I → S.
NPU DMA write: not implemented — NPU is read-only for weight DMA in this design.

duck_coherency_ctrl.sv's actual implementation is a simplification of this: it only tracks a per-line dirty bit (CPU) and a per-line npu_present bit (NPU), which together cover the M→S flush-on-NPU-read and invalidate-on-CPU-write transitions this design actually needs — see duck_coherency_ctrl.md for exactly how those two bits implement the table above.

duck_coherency_ctrl.md — the flat-signal RTL implementing this package's protocol
architecture.md — "Why MOESI (not MESI or MOSI)?" explains why that's the name even though OWNED isn't separately implemented

rtl/duck_cache_pkg.sv — Cache/Coherency Types Reference (docs-only)