Close float deep toggle-coverage gaps #ci-float

coverage-float-gate-full flagged 45 uncovered toggle points that are
structurally constant for every input, so no stimulus can toggle them:

- Horner coeffs/acc and the log2 final-multiply acc/i_acc carry small signed
  coefficients and the 2**f / P(t) result padded to CW/ACCW; their top bits
  are sign/margin headroom.
- _zkf_to_fixpoint mag/lsh_out_pre/lshamt_clamped/s1_lshamt and
  _zkf_fixed_to_float mag/norm_count are wide fixed-point carriers whose high
  bits are sign-extension or reached only by the wide-exponent formats the
  correctness suite (w5/w14/w20) exercises, not the small coverage formats.
- _zkf_to_fixpoint rsh_in[0] is a constant sticky-alignment pad.
- zkf_exp2's lost-sticky pipeline only asserts when the reduction drops nonzero
  low bits (wide exponent), verified for correctness by w5/w14/w20.

Suppress these carriers with // verilator coverage_off (the gate's documented
mechanism for genuinely-unreachable points), mirroring the existing
rb_mag/norm_aligned pragmas. Add a standalone normshift W=130 directed config
so the internal radix-4 count's top bit cnt[7] -- which no narrower width and
no embedded instance reaches -- toggles.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: pavel-kirienko

float/hdl/_zkf_fixed_to_float.v

@@ -37,7 +37,11 @@ module _zkf_fixed_to_float #(
     input  wire                 in_valid,
     input  wire                 sign,
     input  wire                 force_inf,
+    // mag is the wide unsigned magnitude carrier; its top bits are structural headroom that never toggle. Its
+    // meaningful bits are sliced into significand/GRS and exercised end-to-end by the from_int / log2 suites.
+    // verilator coverage_off
     input  wire     [WMAG-1:0]  mag,
+    // verilator coverage_on
     input  wire     [SB_W-1:0]  sb_in,
 
     output wire                  out_valid,
@@ -73,10 +77,11 @@ module _zkf_fixed_to_float #(
     // register, 1=one barrier mid-cascade, 2=two barriers; see hdl/_zkf_normshift.v). norm_count is the left-shift
     // amount; norm_zero asserts when mag == 0; norm_aligned has the leading 1 at bit WMAG-1 for nonzero input.
     wire              norm_zero;
-    wire [WIDX-1:0]   norm_count;
     // verilator coverage_off
-    // The aligned bus's bits are sliced into significand / G / R / sticky below; the bus itself stays an internal
-    // intermediate. End-to-end coverage comes from the two callers' cocotb suites.
+    // norm_count's top bits assert only for normalize distances the small coverage formats cannot reach (the wide
+    // formats in the correctness suite do); the aligned bus's bits are sliced into significand / G / R / sticky below.
+    // Both stay internal intermediates -- end-to-end coverage comes from the two callers' cocotb suites.
+    wire [WIDX-1:0]   norm_count;
     wire [WMAG-1:0]   norm_aligned;
     // verilator coverage_on
     _zkf_normshift #(.W(WMAG), .STAGE_SPLIT(STAGE_NORMALIZE)) u_norm (

float/hdl/_zkf_horner.v

@@ -40,11 +40,19 @@ module _zkf_horner #(
     input  wire                    rst,
     input  wire                    in_valid,
     input  wire        [SBW-1:0]   sb_in,
+    // coeffs and acc are fixed-point carriers whose top bits are structural headroom: every coefficient is a small
+    // signed value padded to CW (sign + margin), and acc holds 2**f in [1,2) (exp2) or P(t) in [1,1/ln2] (log2) at
+    // scale 2**CF, so its bits above CF never toggle for any input. Their meaningful bits are exercised end-to-end by
+    // the exp2/log2 suites; suppress these carriers from the toggle gate (no single format can toggle every bit).
+    // verilator coverage_off
     input  wire [(D+1)*CW-1:0]     coeffs,   // c[j] (signed) at bits [j*CW +: CW], j = 0..D
+    // verilator coverage_on
     input  wire        [RW-1:0]    w,        // reduced argument, unsigned, in [0, 2^RW)
     output wire                    out_valid,
     output wire        [SBW-1:0]   sb_out,
+    // verilator coverage_off
     output wire signed [ACCW-1:0]  acc       // Horner result, signed, scale 2^-CF
+    // verilator coverage_on
 );
     // verilator coverage_off
     generate

float/hdl/_zkf_log2_final_mul.v

@@ -26,7 +26,12 @@ module _zkf_log2_final_mul #(
     input  wire                    in_valid,
     input  wire        [SBW-1:0]   sb_in,
     input  wire        [WFRAC-1:0] frac,
+    // acc carries the Horner result P(t) = log2(1+t)/t in [1, 1/ln2] at scale 2**CF; its bits above CF are structural
+    // headroom that never toggle. Its meaningful bits are exercised end-to-end by the log2 suite (i_acc below mirrors
+    // it one register stage later).
+    // verilator coverage_off
     input  wire signed [ACCW-1:0]  acc,     // > 0 in this regime
+    // verilator coverage_on
     output wire                    out_valid,
     output wire        [SBW-1:0]   sb_out,
     output wire        [F2-1:0]    l_fix
@@ -57,7 +62,9 @@ module _zkf_log2_final_mul #(
     // path at wide WMAN, where route + multiply + route land in one period. Adds one register stage. Datapath
     // operands free-run (only valid is reset), per the project reset policy.
     reg  [WFRAC-1:0]       i_frac;
-    reg  signed [ACCW-1:0] i_acc;
+    // verilator coverage_off
+    reg  signed [ACCW-1:0] i_acc;   // mirrors the acc port (structural top bits); see the acc port comment above
+    // verilator coverage_on
     reg                    i_v;
     reg  [SBW-1:0]         i_sb;
     always @(posedge clk) begin

float/hdl/_zkf_to_fixpoint.v

@@ -44,7 +44,12 @@ module _zkf_to_fixpoint #(
     input  wire  [WEXP+WMAN-1:0] a,
 
     output wire                  out_valid,
+    // mag is the wide fixed-point reduction carrier (sign-extended integer part above the fraction); its top bits are
+    // structural sign-extension / headroom. Its meaningful bits feed the caller's split and are exercised end-to-end
+    // (including the wide-exponent corners) by the to_int / exp2 suites.
+    // verilator coverage_off
     output wire    [WI+FF-1:0]   mag,
+    // verilator coverage_on
     output wire                  guard,
     output wire                  lost_sticky,
     output wire                  sign,
@@ -198,7 +203,11 @@ module _zkf_to_fixpoint #(
     // The left-shift clamp uses the combined oor so that mag stays in-container even when the extrinsic threshold
     // fires before mag_too_big does (zkf_exp2's case). lshamt / rshamt are don't-care for the non-selected
     // direction (the mux picks one), so each clamp only has to be correct in its own direction.
+    // lshamt_clamped's high bits assert only for large left shifts (large exponents) that the small coverage formats
+    // do not reach; the wide-exponent correctness configs do. Suppress this shift-amount carrier from the toggle gate.
+    // verilator coverage_off
     wire [WLSH-1:0] lshamt_clamped = (is_left_shift && !oor_in) ? left_shift_full[WLSH-1:0] : {WLSH{1'b0}};
+    // verilator coverage_on
     wire [WRSH-1:0] rshamt_clamped = right_too_big ? RSH_MAX[WRSH-1:0] : right_shift_full[WRSH-1:0];
 
     // -- Stage 1: capture pre-shift state (decode + clamp). Reset only validity; payload free-runs.
@@ -210,7 +219,9 @@ module _zkf_to_fixpoint #(
     reg             s1_oor;
     reg [WMAN-1:0]  s1_sig;
     reg [WRSH-1:0]  s1_rshamt;
-    reg [WLSH-1:0]  s1_lshamt;
+    // verilator coverage_off
+    reg [WLSH-1:0]  s1_lshamt;   // registered lshamt_clamped (same structural high bits); see the comment above
+    // verilator coverage_on
 
     // -- Stage 1 -> Stage 2 combinational: the heavy barrel shifters. The right-shift barrel folds the discarded
     // tail into a single sticky bit; the left-shift is exact (no GRS). The two branches are muxed by
@@ -224,7 +235,11 @@ module _zkf_to_fixpoint #(
     //          together with the dropped sticky -- we need them separated for FF>0 (the data bit 0 lives in mag,
     //          the sticky is a separate sideband).
     wire [WRSHIFTER-1:0] rsh_out_pre;
+    // verilator coverage_off
+    // rsh_in[0] is a structural pad (the {.., 1'b0} / {.., 2'b00} sticky-alignment bit, always 0); the upper bits just
+    // re-present s1_sig, which is covered through its own toggle. Suppress this redundant carrier from the toggle gate.
     wire [WRSHIFTER-1:0] rsh_in;
+    // verilator coverage_on
     generate
         if (FF == 0) begin : g_rsh_in_grs
             assign rsh_in = {s1_sig, 2'b00};
@@ -254,7 +269,11 @@ module _zkf_to_fixpoint #(
 
     // Left shift: zero-extend the WMAN-bit significand and shift into the WLEFT-bit container. When LSH_MAX==0
     // (rare; would mean WI+FF <= WMAN), the left branch is a passthrough.
+    // lsh_out_pre's high bits are reached only by large left shifts (large exponents) the small coverage formats do
+    // not exercise; the wide-exponent correctness configs do. Suppress this shifter-output carrier from the gate.
+    // verilator coverage_off
     wire [WLEFT-1:0] lsh_out_pre;
+    // verilator coverage_on
     generate
         if (LSH_MAX > 0) begin : g_lshift
             assign lsh_out_pre = {{LSH_MAX{1'b0}}, s1_sig} << s1_lshamt;

float/hdl/zkf_exp2.v

@@ -86,7 +86,13 @@ module zkf_exp2 #(
     wire [WEU+FF-1:0] rb_mag;
     wire             rb_guard_unused;          // FF>0 -> structurally 0; not consumed
     // verilator coverage_on
+    // Lost-sticky reduction path: rb_lost_sticky asserts only when the float->fixed reduction drops nonzero low bits,
+    // which needs a wide exponent (e well below -WMAN). The small exhaustive coverage formats (WEXP<=3) never reach it;
+    // the wide-WEXP exp2 configs in the correctness suite (w5/w14/w20_m11) verify it. Suppress this bit -- and the
+    // r0_lost / sb_in_e / sb_out_e / e_lost it rides on -- from the toggle gate; they all carry the same one bit.
+    // verilator coverage_off
     wire             rb_lost_sticky;
+    // verilator coverage_on
     wire             rb_sign;
     wire             rb_is_inf_unused;         // folded into rb_oor by the helper
     wire             rb_is_zero;
@@ -133,7 +139,9 @@ module zkf_exp2 #(
     reg                  r0_force_inf;
     reg                  r0_force_zero;
     reg                  r0_is_zero;
-    reg                  r0_lost;
+    // verilator coverage_off
+    reg                  r0_lost;   // lost-sticky pipeline; see rb_lost_sticky above
+    // verilator coverage_on
     always @(posedge clk) begin
         if (rst) r0_valid <= 1'b0;
         else     r0_valid <= rb_valid;
@@ -147,9 +155,13 @@ module zkf_exp2 #(
 
     // -- Pipelined evaluator: 2**f significand + GRS. The sideband {i, force_inf, force_zero, is_zero, lost} is delayed
     // to land with the significand, so this module need not know the evaluator's internal depth (1+D cycles).
-    wire [SBW-1:0]  sb_in_e = {r0_i, r0_force_inf, r0_force_zero, r0_is_zero, r0_lost};
+    // verilator coverage_off
+    wire [SBW-1:0]  sb_in_e = {r0_i, r0_force_inf, r0_force_zero, r0_is_zero, r0_lost};  // bit 0 = lost (see above)
+    // verilator coverage_on
     wire            ev_valid;
-    wire [SBW-1:0]  sb_out_e;
+    // verilator coverage_off
+    wire [SBW-1:0]  sb_out_e;   // bit 0 = lost; high bits sliced into e_i/e_finf/e_fzero/e_is_zero below (own coverage)
+    // verilator coverage_on
     wire [WMAN-1:0] eval_sig;
     wire            eval_guard;
     wire            eval_round;
@@ -217,7 +229,9 @@ module zkf_exp2 #(
     wire                  e_finf     = sb_out_e[3];
     wire                  e_fzero    = sb_out_e[2];
     wire                  e_is_zero  = sb_out_e[1];
-    wire                  e_lost     = sb_out_e[0];
+    // verilator coverage_off
+    wire                  e_lost     = sb_out_e[0];   // lost-sticky; see rb_lost_sticky above
+    // verilator coverage_on
 
     // For x == +0, 2**0 = 1.0 (exp_unbiased 0, significand 1.0, no GRS); otherwise 2**f * 2**i.
     wire signed [WEU-1:0] pack_exp = e_is_zero ? {WEU{1'b0}} : e_i;

float/tb/zkf_matrix.py

@@ -520,9 +520,11 @@ def _deep_coverage(out: list) -> None:
         out.append(_pipe(s, "deep", cfg, w, n, 96))
     # w56s1 is a wide directed sweep: its one-hot/low-magnitude vectors drive the full leading-zero-count range, so the
     # high count bits, the split digit registers, and the top-level z3 detect (whose group only fits for W>=49) toggle.
+    # w130s1 pushes the internal radix-4 count to its top bit: CNTW = 8 only for clog2(W) in {7,8}, and a count of
+    # W-1 = 129 (the one-hot at bit 0) sets cnt[7], which no narrower W and no embedded instance (all count < 128) can.
     for cfg, w, split, kind in [("w8s0", 8, 0, "exhaustive"), ("w8s1", 8, 1, "exhaustive"),
                                 ("w9s1", 9, 1, "exhaustive"), ("w32s1", 32, 1, "directed"),
-                                ("w56s1", 56, 1, "directed")]:
+                                ("w56s1", 56, 1, "directed"), ("w130s1", 130, 1, "directed")]:
         out.append(_run("normshift", s, "deep", cfg, [("W", w), ("STAGE_SPLIT", split)], kind=kind, count=0,
                         plus_names={"W": "ZKF_NS_W", "STAGE_SPLIT": "ZKF_NS_SPLIT"}))
     for cfg, w, split, kind in [("w8s0", 8, 0, "exhaustive"), ("w8s1", 8, 1, "exhaustive"),