feat(hw/rtl): implement full Top-K CAM search pipeline with serial result output

- add TOPK_K, FIFO_DEPTH, RESULT_SERIAL parameters to cam_params
- add candidate_fifo: synchronous ready/valid FIFO for (row, score) candidates
- add topk_tracker: tracks top-K candidates with clear/ready handshake
- add result_serializer: serializes packed Top-K array into rank-ordered stream
- refactor match_engine_pipeline from 4-state to 8-state Top-K pipeline
- extend cam_top with serial Top-K interface (result_rank/row/score/last)
- add backward-compatible top1_index/top1_score aliases from rank-0 beat
- add comprehensive tests for all new modules

hw/rtl/cam_params.svh

@@ -9,6 +9,9 @@
 //   NUM_ROWS    — Number of rows in the CAM array
 //   HASH_BITS   — Width of the hash value in bits
 //   LANES       — Number of parallel comparison lanes
+//   TOPK_K     — Number of best matches retained per query
+//   FIFO_DEPTH — Candidate FIFO entries between match engine and tracker
+//   RESULT_SERIAL — Enables rank-ordered serial result output
 //   ROW_BITS    — Bits needed to index NUM_ROWS rows ($clog2(NUM_ROWS))
 //   SCORE_BITS  — Bits needed to represent HASH_BITS-bit scores ($clog2(HASH_BITS+1))
 //
@@ -34,6 +37,21 @@
 `define LANES 8
 `endif
 
+// Number of Top-K results to retain and serialize.
+`ifndef TOPK_K
+`define TOPK_K 4
+`endif
+
+// Candidate FIFO depth between score generation and Top-K tracking.
+`ifndef FIFO_DEPTH
+`define FIFO_DEPTH 16
+`endif
+
+// Result interface mode. First implementation uses serial Top-K output.
+`ifndef RESULT_SERIAL
+`define RESULT_SERIAL 1
+`endif
+
 // Bits required to represent a row index.
 `ifndef ROW_BITS
 `define ROW_BITS $clog2(`NUM_ROWS)