1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

// formal: prove 5 expect pass slang top pipe3_eq
`define FORMAL
// pipe3: three-stage arithmetic pipeline, y = ((a + b)[3:0] * c[3:0]) + 1 (8 bits). Registers: stage 1
// {s = a + b, c1 = c[3:0]}, stage 2 {p = s[3:0] * c1}, stage 3 {y = p + 1}. Latency 3 cycles. Synchronous
// active-high reset clears every register. Only a[3:0], b[3:0], c[3:0] influence y.
// pipe3_retimed: the same function and latency with the registers moved across the multiplier: stage 2
// {s2 = s[3:0], c2 = c1}, stage 3 {y = s2 * c2 + 1}. BUG selects a variant of the twin.
// pipe3_eq: a miter of pipe3 against pipe3_retimed with common inputs and reset; BUG goes to the twin.
module pipe3 #(parameter CHECK = 1) (
  input  wire       clk,
  input  wire       rst,
  input  wire [7:0] a,
  input  wire [7:0] b,
  input  wire [7:0] c,
  output reg  [7:0] y,
  output wire [7:0] dbg_p          // stage-2 register, exposed for the miter's helper assertion
);
  reg [7:0] s;
  reg [3:0] c1;
  reg [7:0] p;
  assign dbg_p = p;
  always @(posedge clk) begin
    if (rst) begin s <= 8'd0; c1 <= 4'd0; p <= 8'd0; y <= 8'd0; end
    else begin
      s  <= a + b;
      c1 <= c[3:0];
      p  <= s[3:0] * c1;
      y  <= p + 8'd1;
    end
  end

`ifdef FORMAL
  // CHECK=0 switches the properties off (used when pipe3 sits inside the miter)
  generate if (CHECK) begin : g_chk
  reg init = 1'b1;
  always @(posedge clk) init <= 1'b0;
  always @(*) if (init) assume (rst);

  // hist counts clean cycles since reset (saturates at 3): y is only specified after 3
  reg [1:0] hist;
  always @(posedge clk) begin
    if (rst) hist <= 2'd0;
    else if (hist != 2'd3) hist <= hist + 2'd1;
  end

  // input history as plain registers
  reg [3:0] sa1, sb1, sc1, sa2, sb2, sc2, sa3, sb3, sc3;
  always @(posedge clk) begin
    sa1 <= a[3:0]; sb1 <= b[3:0]; sc1 <= c[3:0];
    sa2 <= sa1;    sb2 <= sb1;    sc2 <= sc1;
    sa3 <= sa2;    sb3 <= sb2;    sc3 <= sc2;
  end
  wire [3:0] sum3 = sa3 + sb3;       // low 4 bits of a + b three cycles ago

  // functional property with latency 3, checked only after 3 clean cycles
  always @(*) if (!init && hist == 2'd3) a_latency3: assert (y == (sum3 * sc3) + 8'd1);
  // the cycle after a reset the output register is 0
  always @(posedge clk) if (!init && $past(rst)) a_reset_zero: assert (y == 8'd0);
  always @(*) if (!init) c_y_nonzero: cover (hist == 2'd3 && y == 8'd7);
  end endgenerate
`endif
endmodule

module pipe3_retimed #(parameter BUG = 0) (
  input  wire       clk,
  input  wire       rst,
  input  wire [7:0] a,
  input  wire [7:0] b,
  input  wire [7:0] c,
  output reg  [7:0] y,
  output wire [3:0] dbg_s2,        // stage-2 registers, exposed for the miter's helper assertion
  output wire [3:0] dbg_c2
);
  reg [7:0] s;
  reg [3:0] c1;
  reg [3:0] s2, c2;
  assign dbg_s2 = s2;
  assign dbg_c2 = c2;
  always @(posedge clk) begin
    if (rst) begin s <= 8'd0; c1 <= 4'd0; s2 <= 4'd0; c2 <= 4'd0; y <= 8'd0; end
    else begin
      s  <= a + b;
      c1 <= c[3:0];
      s2 <= s[3:0];
      c2 <= c1;
      y  <= s2 * ((BUG == 1) ? {1'b0, c2[2:0]} : c2) + 8'd1;
    end
  end
endmodule

module pipe3_eq #(parameter BUG = 0, parameter HELPER = 1) (
  input  wire       clk,
  input  wire       rst,
  input  wire [7:0] a,
  input  wire [7:0] b,
  input  wire [7:0] c,
  output wire       same
);
  wire [7:0] y1, y2, p_ref;
  wire [3:0] s2_ret, c2_ret;
  pipe3 #(.CHECK(0))     u_ref (.clk(clk), .rst(rst), .a(a), .b(b), .c(c), .y(y1), .dbg_p(p_ref));
  pipe3_retimed #(.BUG(BUG)) u_ret (.clk(clk), .rst(rst), .a(a), .b(b), .c(c), .y(y2), .dbg_s2(s2_ret), .dbg_c2(c2_ret));
  assign same = (y1 == y2);

`ifdef FORMAL
  reg init = 1'b1;
  always @(posedge clk) init <= 1'b0;
  always @(*) if (init) assume (rst);
  always @(*) if (!init) a_equiv: assert (same);
  // helper assertion across the moved register cut: the reference's stage-2 register equals the
  // twin's stage-2 registers multiplied
  generate if (HELPER) begin : g_helper
    always @(*) if (!init) h_cut: assert (p_ref == s2_ret * c2_ret);
  end endgenerate
  always @(*) if (!init) c_nonzero: cover (y1 == 8'd7 && y2 == 8'd7);
`endif
endmodule

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

// formal: cover 6 expect reached slang top pipe3_eq
`define FORMAL
// pipe3: three-stage arithmetic pipeline, y = ((a + b)[3:0] * c[3:0]) + 1 (8 bits). Registers: stage 1
// {s = a + b, c1 = c[3:0]}, stage 2 {p = s[3:0] * c1}, stage 3 {y = p + 1}. Latency 3 cycles. Synchronous
// active-high reset clears every register. Only a[3:0], b[3:0], c[3:0] influence y.
// pipe3_retimed: the same function and latency with the registers moved across the multiplier: stage 2
// {s2 = s[3:0], c2 = c1}, stage 3 {y = s2 * c2 + 1}. BUG selects a variant of the twin.
// pipe3_eq: a miter of pipe3 against pipe3_retimed with common inputs and reset; BUG goes to the twin.
module pipe3 #(parameter CHECK = 1) (
  input  wire       clk,
  input  wire       rst,
  input  wire [7:0] a,
  input  wire [7:0] b,
  input  wire [7:0] c,
  output reg  [7:0] y,
  output wire [7:0] dbg_p          // stage-2 register, exposed for the miter's helper assertion
);
  reg [7:0] s;
  reg [3:0] c1;
  reg [7:0] p;
  assign dbg_p = p;
  always @(posedge clk) begin
    if (rst) begin s <= 8'd0; c1 <= 4'd0; p <= 8'd0; y <= 8'd0; end
    else begin
      s  <= a + b;
      c1 <= c[3:0];
      p  <= s[3:0] * c1;
      y  <= p + 8'd1;
    end
  end

`ifdef FORMAL
  // CHECK=0 switches the properties off (used when pipe3 sits inside the miter)
  generate if (CHECK) begin : g_chk
  reg init = 1'b1;
  always @(posedge clk) init <= 1'b0;
  always @(*) if (init) assume (rst);

  // hist counts clean cycles since reset (saturates at 3): y is only specified after 3
  reg [1:0] hist;
  always @(posedge clk) begin
    if (rst) hist <= 2'd0;
    else if (hist != 2'd3) hist <= hist + 2'd1;
  end

  // input history as plain registers
  reg [3:0] sa1, sb1, sc1, sa2, sb2, sc2, sa3, sb3, sc3;
  always @(posedge clk) begin
    sa1 <= a[3:0]; sb1 <= b[3:0]; sc1 <= c[3:0];
    sa2 <= sa1;    sb2 <= sb1;    sc2 <= sc1;
    sa3 <= sa2;    sb3 <= sb2;    sc3 <= sc2;
  end
  wire [3:0] sum3 = sa3 + sb3;       // low 4 bits of a + b three cycles ago

  // functional property with latency 3, checked only after 3 clean cycles
  always @(*) if (!init && hist == 2'd3) a_latency3: assert (y == (sum3 * sc3) + 8'd1);
  // the cycle after a reset the output register is 0
  always @(posedge clk) if (!init && $past(rst)) a_reset_zero: assert (y == 8'd0);
  always @(*) if (!init) c_y_nonzero: cover (hist == 2'd3 && y == 8'd7);
  end endgenerate
`endif
endmodule

module pipe3_retimed #(parameter BUG = 0) (
  input  wire       clk,
  input  wire       rst,
  input  wire [7:0] a,
  input  wire [7:0] b,
  input  wire [7:0] c,
  output reg  [7:0] y,
  output wire [3:0] dbg_s2,        // stage-2 registers, exposed for the miter's helper assertion
  output wire [3:0] dbg_c2
);
  reg [7:0] s;
  reg [3:0] c1;
  reg [3:0] s2, c2;
  assign dbg_s2 = s2;
  assign dbg_c2 = c2;
  always @(posedge clk) begin
    if (rst) begin s <= 8'd0; c1 <= 4'd0; s2 <= 4'd0; c2 <= 4'd0; y <= 8'd0; end
    else begin
      s  <= a + b;
      c1 <= c[3:0];
      s2 <= s[3:0];
      c2 <= c1;
      y  <= s2 * ((BUG == 1) ? {1'b0, c2[2:0]} : c2) + 8'd1;
    end
  end
endmodule

module pipe3_eq #(parameter BUG = 0, parameter HELPER = 1) (
  input  wire       clk,
  input  wire       rst,
  input  wire [7:0] a,
  input  wire [7:0] b,
  input  wire [7:0] c,
  output wire       same
);
  wire [7:0] y1, y2, p_ref;
  wire [3:0] s2_ret, c2_ret;
  pipe3 #(.CHECK(0))     u_ref (.clk(clk), .rst(rst), .a(a), .b(b), .c(c), .y(y1), .dbg_p(p_ref));
  pipe3_retimed #(.BUG(BUG)) u_ret (.clk(clk), .rst(rst), .a(a), .b(b), .c(c), .y(y2), .dbg_s2(s2_ret), .dbg_c2(c2_ret));
  assign same = (y1 == y2);

`ifdef FORMAL
  reg init = 1'b1;
  always @(posedge clk) init <= 1'b0;
  always @(*) if (init) assume (rst);
  always @(*) if (!init) a_equiv: assert (same);
  // helper assertion across the moved register cut: the reference's stage-2 register equals the
  // twin's stage-2 registers multiplied
  generate if (HELPER) begin : g_helper
    always @(*) if (!init) h_cut: assert (p_ref == s2_ret * c2_ret);
  end endgenerate
  always @(*) if (!init) c_nonzero: cover (y1 == 8'd7 && y2 == 8'd7);
`endif
endmodule

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

# ---- formal lab results ledger, engine v2: every row cites a typed run (kind, depth, outcome[, design]) ----
STATUS = ("proven", "bounded", "cex", "cover-reached", "inconclusive")
FROM_RUN = {"proven": {("prove", "proved")},
            "bounded": {("bmc", "bounded")},
            "cex": {("bmc", "counterexample"), ("prove", "counterexample")},
            "cover-reached": {("cover", "reached")},
            "inconclusive": {("prove", "unproven"), ("cover", "not-reached")}}
NEED = {"sync_fifo": 9, "rr_arbiter": 5, "hs_bridge": 4, "csr_block": 3,
        "pipe3": 5, "pipe3_eq": 5, "mod10_counter": 15, "toggle_demo": 4}
KEYS = ("property", "design", "status", "bound", "why", "run", "assumes", "cover", "kills", "rev")
REV = 3
ALWAYS = "reset-at-step-0"
TRACKED = "tracked-constant-stable"
def row_problems(e, runs, tracked):
    n = e.get("property", "?")
    miss = [k for k in KEYS if k not in e]
    if miss:
        return ["missing-field:%s:%s" % (n, ",".join(miss))]
    if e["status"] not in STATUS:
        return ["bad-status:" + n]
    p = []
    if e["rev"] != REV:
        p.append("stale:" + n)
    if e["run"] not in runs:
        return p + ["no-such-run:" + n]
    kind, depth, outcome = runs[e["run"]][:3]
    if len(runs[e["run"]]) > 3 and runs[e["run"]][3] != e["design"]:
        p.append("run-of-another-design:" + n)         # a run typed with its design may be cited only by that design's rows
    if (kind, outcome) not in FROM_RUN[e["status"]]:
        p.append("status-not-from-run:" + n)
    if e["bound"] != depth:
        p.append("bound-not-run-depth:" + n)
    has_cover = bool(str(e["cover"]).strip())
    if e["status"] in ("proven", "bounded") and not (has_cover and e["kills"]):
        p.append("no-evidence:" + n)
    if e["status"] == "cover-reached" and not has_cover:
        p.append("no-evidence:" + n)
    if e["status"] == "cex" and not e["kills"]:
        p.append("no-evidence:" + n)
    if e["status"] == "bounded":
        if e["design"] not in NEED:
            p.append("unknown-design:" + n)
        elif depth < NEED[e["design"]]:
            p.append("short-bound:" + n)
        if len(str(e["why"]).strip()) < 12:
            p.append("unjustified:" + n)
    if ALWAYS not in e["assumes"]:
        p.append("hidden-assume:%s:%s" % (n, ALWAYS))
    if n in tracked and TRACKED not in e["assumes"]:
        p.append("hidden-assume:%s:%s" % (n, TRACKED))
    return p
def ledger_ok(ledger, runs, required, mutants, register, tracked, final=True):
    names = [e.get("property") for e in ledger]
    bad = ["duplicate:" + n for n in sorted({n for n in names if names.count(n) > 1})]
    bad += ["missing-row:" + r for r in sorted(set(required) - set(names))]
    bad += [q for e in ledger for q in row_problems(e, runs, tracked)]
    good = [e for e in ledger if not row_problems(e, runs, tracked)]      # only a row without complaints counts as evidence
    solid = {e["property"] for e in good if e["status"] in ("proven", "cover-reached")}
    for a, rows in sorted(register.items()):
        if rows is None:
            if final:
                bad.append("deferred-assume:" + a)      # a stage may defer a discharge; a final package may not
        elif not (rows and all(r in solid for r in rows)):
            bad.append("open-assume:" + a)
    bad += ["unregistered-assume:%s:%s" % (e.get("property"), a) for e in ledger
            for a in e.get("assumes", []) if a not in register]
    killed = {m for e in good if e["status"] == "cex" for m in e["kills"]}
    bad += ["survivor:" + m for m in sorted(set(mutants) - killed)]
    bad += ["unsupported-kill:%s:%s" % (e.get("property"), m) for e in ledger
            if e.get("status") in ("proven", "bounded") for m in e.get("kills", []) if m not in killed]
    return bad
def mutation_score(ledger, mutants):
    assert mutants, "no mutants registered"
    killed = {m for e in ledger if e.get("status") == "cex" for m in e.get("kills", [])}
    return len(killed & set(mutants)) / len(mutants)

RUNS = {
    "twin-prove": ("prove", 5, "proved"),
    "twin-cover": ("cover", 6, "reached"),
}
REQUIRED = ["twin-equivalence", "twin-needs-cut-helper", "twin-cover"]
MUTANTS = ["twin-W1"]
REGISTER = {"reset-at-step-0": None}                 # discharged by the pair rows of stage 2
YOUR_ROWS = []          # fill from your own runs
bad = ledger_ok(YOUR_ROWS, RUNS, REQUIRED, MUTANTS, REGISTER, set(), final=False)
if YOUR_ROWS:
    assert bad == [], bad
    print("PASS: stage 3 twin package consistent")
else:
    expected = ["missing-row:" + r for r in REQUIRED] + ["survivor:" + m for m in MUTANTS]
    assert sorted(bad) == sorted(expected), bad
    print("PASS: the empty package is rejected with %d complaints" % len(bad))