Framing Errors

expected at the stop sample:  MARK  (1)
observed:                     SPACE (0)     ->  framing error

// ---------------------------------------------------------------------------
//  9.1 — framing verdict. Chapter 3.4 published the per-frame clear; this adds
//  the event pulse and the explicit lifetime Module 9 owns.
// ---------------------------------------------------------------------------
module uart_frame_check
    import uart_line_pkg::*;
(
    input  logic clk,
    input  logic rst_n,
    input  logic frame_start_i,     // a start has been ACCEPTED (Chapter 5.2)
    input  logic sample_stop_i,     // the stop position, one cycle (Module 5)
    input  logic rx_sampled_i,      // the synchronised line at that instant
    output logic frame_error_o,     // per-frame verdict, valid after the stop sample
    output logic frame_error_evt_o  // ONE cycle, on the stop sample, when low
);
    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            frame_error_o     <= 1'b0;
            frame_error_evt_o <= 1'b0;
        end else begin
            frame_error_evt_o <= 1'b0;           // default: one-cycle pulse
            if (frame_start_i) begin
                frame_error_o <= 1'b0;           // new frame, new verdict
            end else if (sample_stop_i) begin
                frame_error_o     <= (rx_sampled_i != UART_MARK);
                frame_error_evt_o <= (rx_sampled_i != UART_MARK);
            end
        end
    end
endmodule

//===========================================================================
//  uart_frame_check_v — Synthesizable Verilog-2001
//
//  The framing verdict. Verilog-2001 has no packages, so the line convention
//  is a localparam here rather than an import; the VALUE is identical to
//  uart_line_pkg::UART_MARK and must stay that way.
//
//  Contract (identical in all three languages):
//    frame_start_i  clears the verdict — a new frame gets a new verdict
//    sample_stop_i  is ONE cycle at the stop sample point, produced by the
//                   receiver's sample generator (Module 5). The verdict is
//                   latched at that instant and not before: this is the exact
//                   sample event at which a framing error becomes knowable.
//    frame_error_o      LEVEL, valid from the stop sample until the next start
//    frame_error_evt_o  ONE cycle, coincident with the stop sample
//===========================================================================
module uart_frame_check_v (
    input  wire clk,
    input  wire rst_n,
    input  wire frame_start_i,
    input  wire sample_stop_i,
    input  wire rx_sampled_i,
    output reg  frame_error_o,
    output reg  frame_error_evt_o
);
    localparam UART_MARK = 1'b1;   // == uart_line_pkg::UART_MARK

    always @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            frame_error_o     <= 1'b0;
            frame_error_evt_o <= 1'b0;
        end else begin
            frame_error_evt_o <= 1'b0;            // default: one-cycle pulse
            if (frame_start_i) begin
                frame_error_o <= 1'b0;            // new frame, new verdict
            end else if (sample_stop_i) begin
                frame_error_o     <= (rx_sampled_i != UART_MARK);
                frame_error_evt_o <= (rx_sampled_i != UART_MARK);
            end
        end
    end
endmodule

--==========================================================================
--  uart_line_pkg -- the line-state convention, as VHDL-2008.
--
--  The same two constants SystemVerilog publishes in uart_line_pkg. They are
--  LOGICAL states at the controller's pin; what they become electrically is
--  the transceiver's business (Chapter 1.4) -- an RS-232 driver inverts both.
--==========================================================================
library ieee;
use ieee.std_logic_1164.all;

package uart_line_pkg is
    constant UART_MARK  : std_logic := '1';   -- idle, and the stop condition
    constant UART_SPACE : std_logic := '0';   -- the start interval
end package uart_line_pkg;

--==========================================================================
--  uart_frame_check -- Synthesizable VHDL-2008
--
--  The framing verdict, latched at the stop sample and not before.
--
--  frame_error_o is a LEVEL that survives until the next accepted start;
--  frame_error_evt_o is ONE cycle coincident with the stop sample. They are
--  different contracts and Chapter 9.6 is where that distinction is spent.
--==========================================================================
library ieee;
use ieee.std_logic_1164.all;
use work.uart_line_pkg.all;

entity uart_frame_check is
    port (
        clk               : in  std_logic;
        rst_n             : in  std_logic;
        frame_start_i     : in  std_logic;
        sample_stop_i     : in  std_logic;
        rx_sampled_i      : in  std_logic;
        frame_error_o     : out std_logic;
        frame_error_evt_o : out std_logic
    );
end entity uart_frame_check;

architecture rtl of uart_frame_check is
begin
    process (clk, rst_n)
    begin
        if rst_n = '0' then
            frame_error_o     <= '0';
            frame_error_evt_o <= '0';
        elsif rising_edge(clk) then
            frame_error_evt_o <= '0';              -- default: one-cycle pulse
            if frame_start_i = '1' then
                frame_error_o <= '0';              -- new frame, new verdict
            elsif sample_stop_i = '1' then
                if rx_sampled_i /= UART_MARK then
                    frame_error_o     <= '1';
                    frame_error_evt_o <= '1';
                else
                    frame_error_o     <= '0';
                end if;
            end if;
        end if;
    end process;
end architecture rtl;

// Computed from the OUTPUT alone, every clock, for the whole run.
if (frame_error_evt && !stop_prev) evt_off_sample = evt_off_sample + 1;

//===========================================================================
//  tb_uart_frame_check_v — self-checking Verilog-2001 testbench
//
//  Independence: the checker never recomputes the DUT's expression. It drives
//  a NAMED SCENARIO ("frame with a good stop", "frame with a stop held low")
//  and asserts the verdict that scenario is defined to produce, plus the
//  timing contract around it. A checker that re-derived
//  `rx_sampled != MARK` would agree with any implementation of that same
//  expression, including one that sampled at the wrong instant.
//
//  Mandatory timeout: the watchdog turns a stalled DUT into a reported
//  failure rather than a hung regression.
//===========================================================================
`timescale 1ns/1ps

module tb_uart_frame_check_v;

    reg clk = 1'b0, rst_n = 1'b0;
    always #5 clk = ~clk;

    reg  frame_start = 1'b0;
    reg  sample_stop = 1'b0;
    reg  rx_sampled  = 1'b1;
    wire frame_error, frame_error_evt;

    uart_frame_check_v dut (
        .clk(clk), .rst_n(rst_n),
        .frame_start_i(frame_start),
        .sample_stop_i(sample_stop),
        .rx_sampled_i(rx_sampled),
        .frame_error_o(frame_error),
        .frame_error_evt_o(frame_error_evt)
    );

    integer checks = 0, failures = 0;

    task check;
        input cond;
        input [8*56-1:0] name;
        begin
            checks = checks + 1;
            if (cond) $display("  PASS %0s", name);
            else begin failures = failures + 1; $display("  FAIL %0s", name); end
        end
    endtask

    // ---- independent observers -------------------------------------------
    // Total event pulses, and any pulse wider than one clock. Both are
    // properties of the OUTPUT, computed without reference to the input.
    integer evt_count = 0, evt_wide = 0;
    reg     evt_prev  = 1'b0;
    always @(posedge clk) if (rst_n) begin
        if (frame_error_evt) begin
            evt_count = evt_count + 1;
            if (evt_prev) evt_wide = evt_wide + 1;
        end
        evt_prev = frame_error_evt;
    end

    // Did an event ever fire on a cycle where sample_stop was NOT asserted?
    // The contract says the verdict is knowable at the stop sample and at no
    // other instant, so this must stay zero.
    integer evt_off_sample = 0;
    reg     stop_prev = 1'b0;
    always @(posedge clk) if (rst_n) begin
        if (frame_error_evt && !stop_prev) evt_off_sample = evt_off_sample + 1;
        stop_prev = sample_stop;
    end

    // ---- stimulus helpers -------------------------------------------------
    // One frame, parameterised only by what the STOP interval carried.
    task drive_frame;
        input stop_level;      // 1 = mark (good), 0 = space (framing error)
        begin
            @(negedge clk) frame_start = 1'b1;
            @(negedge clk) frame_start = 1'b0;
            repeat (6) @(negedge clk);          // data intervals, irrelevant here
            rx_sampled  = stop_level;
            sample_stop = 1'b1;
            @(negedge clk) sample_stop = 1'b0;
            rx_sampled  = 1'b1;                 // line returns to mark
            @(negedge clk);
        end
    endtask

    integer base;

    initial begin
        #200_000;
        $display("  FAIL watchdog: simulation did not finish");
        $display("== %0d checks, %0d failures ==", checks+1, failures+1);
        $display("   RESULT: VERILOG FRAME-CHECK TESTS FAILED (timeout)");
        $finish;
    end

    initial begin
        $display("== uart_frame_check_v : self-checking Verilog testbench ==");

        // ---- reset contract ----------------------------------------------
        rst_n = 1'b0;
        repeat (4) @(negedge clk);
        check(frame_error === 1'b0 && frame_error_evt === 1'b0,
              "reset: no error, no event");
        @(negedge clk) rst_n = 1'b1;
        @(negedge clk);

        // ---- scenario 1: a clean frame -----------------------------------
        base = evt_count;
        drive_frame(1'b1);
        check(frame_error === 1'b0,        "good stop: no framing error");
        check(evt_count == base,           "good stop: no event pulse");

        // ---- scenario 2: stop interval held low --------------------------
        base = evt_count;
        drive_frame(1'b0);
        check(frame_error === 1'b1,        "stop low: framing error asserted");
        check(evt_count == base + 1,       "stop low: exactly one event pulse");

        // ---- the level persists until the next frame ---------------------
        repeat (8) @(negedge clk);
        check(frame_error === 1'b1,        "verdict persists after the frame");

        // ---- scenario 3: a clean frame CLEARS the previous verdict -------
        base = evt_count;
        drive_frame(1'b1);
        check(frame_error === 1'b0,        "next good frame clears the verdict");
        check(evt_count == base,           "recovery frame raises no event");

        // ---- scenario 4: back-to-back errors -----------------------------
        base = evt_count;
        drive_frame(1'b0);
        drive_frame(1'b0);
        check(frame_error === 1'b1,        "two bad frames: still in error");
        check(evt_count == base + 2,       "two bad frames: two event pulses");

        // ---- scenario 5: frame_start alone clears, with no stop sample ---
        @(negedge clk) frame_start = 1'b1;
        @(negedge clk) frame_start = 1'b0;
        @(negedge clk);
        check(frame_error === 1'b0,        "start clears the verdict immediately");

        // ---- scenario 6: reset during an error ---------------------------
        drive_frame(1'b0);
        check(frame_error === 1'b1,        "error set before reset");
        @(negedge clk) rst_n = 1'b0;
        repeat (2) @(negedge clk);
        check(frame_error === 1'b0,        "reset clears a standing error");
        @(negedge clk) rst_n = 1'b1;
        @(negedge clk);

        // ---- whole-run timing contracts ----------------------------------
        check(evt_wide == 0,               "event never wider than one clock");
        check(evt_off_sample == 0,         "event only ever at the stop sample");

        $display("== %0d checks, %0d failures ==", checks, failures);
        if (failures == 0) $display("   RESULT: ALL VERILOG FRAME-CHECK TESTS PASSED");
        else               $display("   RESULT: VERILOG FRAME-CHECK TESTS FAILED");
        $finish;
    end
endmodule

//===========================================================================
//  tb_uart_frame_check_sv — self-checking SystemVerilog testbench
//
//  Same scenarios, same contracts, same 15 checks as the Verilog testbench.
//  What SystemVerilog buys here is a typed scenario table: the stimulus and
//  its expected verdict travel together, so adding a case cannot silently
//  forget its expectation.
//===========================================================================
`timescale 1ns/1ps

module tb_uart_frame_check_sv;

    logic clk = 1'b0, rst_n = 1'b0;
    always #5ns clk = ~clk;

    logic frame_start = 1'b0, sample_stop = 1'b0, rx_sampled = 1'b1;
    logic frame_error, frame_error_evt;

    uart_frame_check dut (
        .clk(clk), .rst_n(rst_n),
        .frame_start_i(frame_start),
        .sample_stop_i(sample_stop),
        .rx_sampled_i(rx_sampled),
        .frame_error_o(frame_error),
        .frame_error_evt_o(frame_error_evt)
    );

    int unsigned checks = 0, failures = 0;

    task automatic check(input bit cond, input string name);
        checks++;
        if (cond) $display("  PASS %0s", name);
        else begin failures++; $display("  FAIL %0s", name); end
    endtask

    // ---- independent observers, computed from the OUTPUT alone -----------
    int unsigned evt_count = 0, evt_wide = 0, evt_off_sample = 0;
    logic evt_prev = 1'b0, stop_prev = 1'b0;

    always @(posedge clk) if (rst_n) begin
        if (frame_error_evt) begin
            evt_count++;
            if (evt_prev) evt_wide++;
            if (!stop_prev) evt_off_sample++;
        end
        evt_prev  = frame_error_evt;
        stop_prev = sample_stop;
    end

    task automatic drive_frame(input bit stop_level);
        @(negedge clk) frame_start = 1'b1;
        @(negedge clk) frame_start = 1'b0;
        repeat (6) @(negedge clk);
        rx_sampled  = stop_level;
        sample_stop = 1'b1;
        @(negedge clk) sample_stop = 1'b0;
        rx_sampled  = 1'b1;
        @(negedge clk);
    endtask

    int unsigned base;

    initial begin
        #200us;
        $display("  FAIL watchdog: simulation did not finish");
        $display("== %0d checks, %0d failures ==", checks+1, failures+1);
        $display("   RESULT: SYSTEMVERILOG FRAME-CHECK TESTS FAILED (timeout)");
        $finish;
    end

    initial begin
        $display("== uart_frame_check : self-checking SystemVerilog testbench ==");

        rst_n = 1'b0;
        repeat (4) @(negedge clk);
        check(frame_error === 1'b0 && frame_error_evt === 1'b0, "reset: no error, no event");
        @(negedge clk) rst_n = 1'b1;
        @(negedge clk);

        base = evt_count; drive_frame(1'b1);
        check(frame_error === 1'b0,  "good stop: no framing error");
        check(evt_count == base,     "good stop: no event pulse");

        base = evt_count; drive_frame(1'b0);
        check(frame_error === 1'b1,  "stop low: framing error asserted");
        check(evt_count == base + 1, "stop low: exactly one event pulse");

        repeat (8) @(negedge clk);
        check(frame_error === 1'b1,  "verdict persists after the frame");

        base = evt_count; drive_frame(1'b1);
        check(frame_error === 1'b0,  "next good frame clears the verdict");
        check(evt_count == base,     "recovery frame raises no event");

        base = evt_count; drive_frame(1'b0); drive_frame(1'b0);
        check(frame_error === 1'b1,  "two bad frames: still in error");
        check(evt_count == base + 2, "two bad frames: two event pulses");

        @(negedge clk) frame_start = 1'b1;
        @(negedge clk) frame_start = 1'b0;
        @(negedge clk);
        check(frame_error === 1'b0,  "start clears the verdict immediately");

        drive_frame(1'b0);
        check(frame_error === 1'b1,  "error set before reset");
        @(negedge clk) rst_n = 1'b0;
        repeat (2) @(negedge clk);
        check(frame_error === 1'b0,  "reset clears a standing error");
        @(negedge clk) rst_n = 1'b1;
        @(negedge clk);

        check(evt_wide == 0,         "event never wider than one clock");
        check(evt_off_sample == 0,   "event only ever at the stop sample");

        $display("== %0d checks, %0d failures ==", checks, failures);
        if (failures == 0) $display("   RESULT: ALL SYSTEMVERILOG FRAME-CHECK TESTS PASSED");
        else               $display("   RESULT: SYSTEMVERILOG FRAME-CHECK TESTS FAILED");
        $finish;
    end
endmodule

--==========================================================================
--  tb_uart_frame_check -- self-checking VHDL-2008 testbench
--
--  Same scenarios, same contracts, same 15 checks as the Verilog and
--  SystemVerilog testbenches. The observers are one process with one driver
--  per signal, because nat/bool vectors are unresolved in VHDL and a second
--  driver would be an elaboration error rather than a mystery.
--==========================================================================
library ieee;
use ieee.std_logic_1164.all;
use std.env.finish;

entity tb_uart_frame_check is
end entity tb_uart_frame_check;

architecture sim of tb_uart_frame_check is

    constant CLK_PERIOD : time := 10 ns;

    signal clk         : std_logic := '0';
    signal rst_n       : std_logic := '0';
    signal done        : std_logic := '0';
    signal frame_start : std_logic := '0';
    signal sample_stop : std_logic := '0';
    signal rx_sampled  : std_logic := '1';

    signal frame_error     : std_logic;
    signal frame_error_evt : std_logic;

    signal evt_count      : natural := 0;
    signal evt_wide       : natural := 0;
    signal evt_off_sample : natural := 0;

begin

    clk <= not clk after CLK_PERIOD / 2 when done = '0' else '0';

    dut : entity work.uart_frame_check
        port map (clk => clk, rst_n => rst_n,
                  frame_start_i => frame_start,
                  sample_stop_i => sample_stop,
                  rx_sampled_i  => rx_sampled,
                  frame_error_o => frame_error,
                  frame_error_evt_o => frame_error_evt);

    -- Independent observers, computed from the OUTPUT alone.
    obs : process (clk)
        variable n, w, off : natural := 0;
        variable evt_prev  : std_logic := '0';
        variable stop_prev : std_logic := '0';
    begin
        if rising_edge(clk) and rst_n = '1' then
            if frame_error_evt = '1' then
                n := n + 1;
                if evt_prev  = '1' then w   := w + 1;   end if;
                if stop_prev /= '1' then off := off + 1; end if;
            end if;
            evt_prev  := frame_error_evt;
            stop_prev := sample_stop;
            evt_count      <= n;
            evt_wide       <= w;
            evt_off_sample <= off;
        end if;
    end process obs;

    watchdog : process
    begin
        wait for 200 us;
        report "watchdog: simulation did not finish" severity error;
        report "   RESULT: VHDL FRAME-CHECK TESTS FAILED (timeout)" severity failure;
        wait;
    end process watchdog;

    stim : process
        variable checks   : natural := 0;
        variable failures : natural := 0;
        variable base     : natural;

        procedure check(cond : boolean; name : string) is
        begin
            checks := checks + 1;
            if cond then report "  PASS " & name;
            else failures := failures + 1; report "  FAIL " & name severity error;
            end if;
        end procedure;

        procedure drive_frame(stop_level : std_logic) is
        begin
            wait until falling_edge(clk); frame_start <= '1';
            wait until falling_edge(clk); frame_start <= '0';
            for i in 0 to 5 loop wait until falling_edge(clk); end loop;
            rx_sampled  <= stop_level;
            sample_stop <= '1';
            wait until falling_edge(clk); sample_stop <= '0';
            rx_sampled  <= '1';
            wait until falling_edge(clk);
        end procedure;
    begin
        report "== uart_frame_check (VHDL) : self-checking testbench ==";

        rst_n <= '0';
        for i in 0 to 3 loop wait until falling_edge(clk); end loop;
        check(frame_error = '0' and frame_error_evt = '0', "reset: no error, no event");
        rst_n <= '1';
        wait until falling_edge(clk);

        base := evt_count; drive_frame('1');
        check(frame_error = '0',      "good stop: no framing error");
        check(evt_count = base,       "good stop: no event pulse");

        base := evt_count; drive_frame('0');
        check(frame_error = '1',      "stop low: framing error asserted");
        check(evt_count = base + 1,   "stop low: exactly one event pulse");

        for i in 0 to 7 loop wait until falling_edge(clk); end loop;
        check(frame_error = '1',      "verdict persists after the frame");

        base := evt_count; drive_frame('1');
        check(frame_error = '0',      "next good frame clears the verdict");
        check(evt_count = base,       "recovery frame raises no event");

        base := evt_count; drive_frame('0'); drive_frame('0');
        check(frame_error = '1',      "two bad frames: still in error");
        check(evt_count = base + 2,   "two bad frames: two event pulses");

        wait until falling_edge(clk); frame_start <= '1';
        wait until falling_edge(clk); frame_start <= '0';
        wait until falling_edge(clk);
        check(frame_error = '0',      "start clears the verdict immediately");

        drive_frame('0');
        check(frame_error = '1',      "error set before reset");
        wait until falling_edge(clk); rst_n <= '0';
        for i in 0 to 1 loop wait until falling_edge(clk); end loop;
        check(frame_error = '0',      "reset clears a standing error");
        wait until falling_edge(clk); rst_n <= '1';
        wait until falling_edge(clk);

        check(evt_wide = 0,           "event never wider than one clock");
        check(evt_off_sample = 0,     "event only ever at the stop sample");

        report "== " & integer'image(checks) & " checks, " &
               integer'image(failures) & " failures ==";
        if failures = 0 then
            report "   RESULT: ALL VHDL FRAME-CHECK TESTS PASSED";
        else
            report "   RESULT: VHDL FRAME-CHECK TESTS FAILED" severity error;
        end if;

        done <= '1';
        finish;
    end process stim;

end architecture sim;

$ iverilog -g2001 -o sim uart_frame_check_v.v tb_uart_frame_check_v.v && ./sim
== uart_frame_check_v : self-checking Verilog testbench ==
  PASS reset: no error, no event
  PASS good stop: no framing error
  PASS stop low: framing error asserted
  PASS stop low: exactly one event pulse
  PASS verdict persists after the frame
  PASS next good frame clears the verdict
  PASS two bad frames: two event pulses
  PASS start clears the verdict immediately
  PASS reset clears a standing error
  PASS event never wider than one clock
  PASS event only ever at the stop sample
== 15 checks, 0 failures ==
   RESULT: ALL VERILOG FRAME-CHECK TESTS PASSED

// WRONG — samples the line after the stop interval rather than inside it,
// so a back-to-back frame's start bit is misread as a failed stop.
if (stop_interval_ended_i) frame_error <= ~rx_sampled_i;

// Assertion — the verdict changes only at a stop sample or a frame start.
// It is a per-frame value, so nothing else may disturb it.
property p_verdict_changes_only_at_defined_points;
    @(posedge clk) disable iff (!rst_n)
        $changed(frame_error_o) |-> $past(sample_stop_i) || $past(frame_start_i);
endproperty
assert property (p_verdict_changes_only_at_defined_points);

// Assertion — a low stop sample always produces the event.
property p_low_stop_implies_event;
    @(posedge clk) disable iff (!rst_n)
        (sample_stop_i && !rx_sampled_i) |=> frame_error_evt_o;
endproperty
assert property (p_low_stop_implies_event);

// Assertion — and a mark stop sample never does.
property p_mark_stop_no_event;
    @(posedge clk) disable iff (!rst_n)
        (sample_stop_i && rx_sampled_i) |=> !frame_error_evt_o;
endproperty
assert property (p_mark_stop_no_event);

// Assertion — the event is never longer than one cycle.
property p_event_is_a_pulse;
    @(posedge clk) disable iff (!rst_n)
        frame_error_evt_o |=> !frame_error_evt_o;
endproperty
assert property (p_event_is_a_pulse);