Overrun, Underrun and Data Loss

OVERRUN occurs when a frame completes AND the holding register is
occupied AND it is not being emptied on that same clock edge.

// ---------------------------------------------------------------------------
//  9.3 — one-entry receive holding register.
//  POLICY: preserve the held byte, DROP the newly arrived one, flag overrun.
//  Same policy as Chapter 6.5; isolated here so it can be stated and tested.
// ---------------------------------------------------------------------------
module uart_rx_holding #(
    parameter int unsigned DATA_W = 8
) (
    input  logic              clk,
    input  logic              rst_n,
    input  logic              rx_char_valid_i,   // one cycle: a frame completed
    input  logic [DATA_W-1:0] rx_char_data_i,
    output logic [DATA_W-1:0] data_o,
    output logic              data_valid_o,
    input  logic              data_ready_i,
    output logic              overrun_evt_o      // ONE cycle: a character was dropped
);
    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            data_o        <= '0;
            data_valid_o  <= 1'b0;
            overrun_evt_o <= 1'b0;
        end else begin
            overrun_evt_o <= 1'b0;

            // Accept first, so a same-cycle arrival can refill the slot.
            if (data_valid_o && data_ready_i)
                data_valid_o <= 1'b0;

            if (rx_char_valid_i) begin
                if (data_valid_o && !data_ready_i) begin
                    // Slot occupied and not being emptied this cycle: the
                    // NEW character is lost. The held one is not disturbed.
                    overrun_evt_o <= 1'b1;
                end else begin
                    data_o       <= rx_char_data_i;
                    data_valid_o <= 1'b1;
                end
            end
        end
    end
endmodule

//===========================================================================
//  uart_rx_holding_v — Synthesizable Verilog-2001
//
//  One-entry receive holding register.
//  POLICY (not a UART requirement — an architecture choice this IP makes):
//  on a collision the HELD byte is preserved and the NEWLY ARRIVED one is
//  dropped. The alternative — overwrite with the new byte — is equally
//  implementable and gives the opposite data-loss behaviour. Chapter 9.3 §4
//  argues the choice; Module 10 replaces the single slot with a FIFO.
//===========================================================================
module uart_rx_holding_v #(
    parameter DATA_W = 8
) (
    input  wire              clk,
    input  wire              rst_n,
    input  wire              rx_char_valid_i,
    input  wire [DATA_W-1:0] rx_char_data_i,
    output reg  [DATA_W-1:0] data_o,
    output reg               data_valid_o,
    input  wire              data_ready_i,
    output reg               overrun_evt_o
);
    always @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            data_o        <= {DATA_W{1'b0}};
            data_valid_o  <= 1'b0;
            overrun_evt_o <= 1'b0;
        end else begin
            overrun_evt_o <= 1'b0;

            // Accept first, so a same-cycle arrival can refill the slot the
            // consumer is emptying. Ordering these two blocks the other way
            // turns a legal hand-off into a spurious overrun.
            if (data_valid_o && data_ready_i)
                data_valid_o <= 1'b0;

            if (rx_char_valid_i) begin
                if (data_valid_o && !data_ready_i) begin
                    overrun_evt_o <= 1'b1;        // the NEW character is lost
                end else begin
                    data_o       <= rx_char_data_i;
                    data_valid_o <= 1'b1;
                end
            end
        end
    end
endmodule

--==========================================================================
--  uart_rx_holding -- Synthesizable VHDL-2008
--
--  One-entry receive holding register. POLICY: keep the held byte, drop the
--  new one, flag overrun. An architecture choice, not a UART requirement.
--
--  data_valid_o must be READ by the process (the collision test needs it),
--  and VHDL forbids reading an out port -- so the flop is an internal signal
--  with a concurrent assignment to the pin. One flop, one net, in all three
--  languages; VHDL simply names them separately.
--==========================================================================
library ieee;
use ieee.std_logic_1164.all;

entity uart_rx_holding is
    generic (
        DATA_W : positive := 8
    );
    port (
        clk             : in  std_logic;
        rst_n           : in  std_logic;
        rx_char_valid_i : in  std_logic;
        rx_char_data_i  : in  std_logic_vector(DATA_W-1 downto 0);
        data_o          : out std_logic_vector(DATA_W-1 downto 0);
        data_valid_o    : out std_logic;
        data_ready_i    : in  std_logic;
        overrun_evt_o   : out std_logic
    );
end entity uart_rx_holding;

architecture rtl of uart_rx_holding is
    signal data_q  : std_logic_vector(DATA_W-1 downto 0);
    signal valid_q : std_logic;
begin
    data_o       <= data_q;
    data_valid_o <= valid_q;

    process (clk, rst_n)
    begin
        if rst_n = '0' then
            data_q        <= (others => '0');
            valid_q       <= '0';
            overrun_evt_o <= '0';
        elsif rising_edge(clk) then
            overrun_evt_o <= '0';

            -- Accept first, so a same-cycle arrival can refill the slot.
            if valid_q = '1' and data_ready_i = '1' then
                valid_q <= '0';
            end if;

            if rx_char_valid_i = '1' then
                if valid_q = '1' and data_ready_i = '0' then
                    overrun_evt_o <= '1';          -- the NEW character is lost
                else
                    data_q  <= rx_char_data_i;
                    valid_q <= '1';
                end if;
            end if;
        end if;
    end process;
end architecture rtl;

//===========================================================================
//  tb_uart_rx_holding_v — self-checking Verilog-2001 testbench
//
//  INDEPENDENCE: the checker keeps its own model of what SHOULD have reached
//  the consumer — a queue of the bytes the stimulus offered, minus the ones
//  the policy says were dropped — and compares that sequence against what
//  actually came out. It never inspects data_valid_o to decide what the
//  policy was; it decides from the stimulus it drove.
//
//  The POLICY under test (an architecture choice, not a UART rule): on a
//  collision the HELD byte survives and the NEW one is lost.
//===========================================================================
`timescale 1ns/1ps

module tb_uart_rx_holding_v;

    localparam DATA_W = 8;

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

    reg              rx_char_valid = 1'b0;
    reg  [DATA_W-1:0] rx_char_data = 8'h00;
    reg              data_ready    = 1'b0;
    wire [DATA_W-1:0] data;
    wire             data_valid, overrun_evt;

    uart_rx_holding_v #(.DATA_W(DATA_W)) dut (
        .clk(clk), .rst_n(rst_n),
        .rx_char_valid_i(rx_char_valid), .rx_char_data_i(rx_char_data),
        .data_o(data), .data_valid_o(data_valid), .data_ready_i(data_ready),
        .overrun_evt_o(overrun_evt)
    );

    integer checks = 0, failures = 0;

    task check;
        input cond;
        input [8*58-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 observation of what the consumer actually received --
    reg [DATA_W-1:0] got [0:63];
    integer n_got = 0, n_over = 0, over_wide = 0;
    reg over_prev = 1'b0;

    always @(posedge clk) if (rst_n) begin
        if (data_valid && data_ready) begin
            got[n_got] = data;
            n_got = n_got + 1;
        end
        if (overrun_evt) begin
            n_over = n_over + 1;
            if (over_prev) over_wide = over_wide + 1;
        end
        over_prev = overrun_evt;
    end

    task offer;                 // one-cycle arrival of a character
        input [DATA_W-1:0] d;
        begin
            @(negedge clk) rx_char_data = d; rx_char_valid = 1'b1;
            @(negedge clk) rx_char_valid = 1'b0;
        end
    endtask

    // overrun_evt_o is registered, and the observer samples a registered
    // output, so an event is two active edges behind the stimulus that
    // caused it. Counts are only meaningful after this settles -- reading
    // them earlier tests the testbench's timing, not the design's.
    task settle;
        begin repeat (2) @(negedge clk); end
    endtask

    integer base_got, base_over, i;

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

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

        rst_n = 1'b0; data_ready = 1'b0;
        repeat (4) @(negedge clk);
        check(data_valid === 1'b0 && overrun_evt === 1'b0, "reset: empty, no overrun");
        @(negedge clk) rst_n = 1'b1;
        @(negedge clk);

        // ---- one character, then a consumer read --------------------------
        base_got = n_got; base_over = n_over;
        offer(8'h41);
        check(data_valid === 1'b1,   "first character: slot becomes full");
        check(data === 8'h41,        "first character: payload correct");
        check(n_over == base_over,   "first character: no overrun");
        @(negedge clk) data_ready = 1'b1;
        @(negedge clk) data_ready = 1'b0;
        @(negedge clk);
        check(data_valid === 1'b0,   "after the read: slot empties");
        check(n_got == base_got + 1, "after the read: one byte delivered");
        check(got[base_got] == 8'h41,"delivered byte is the one offered");

        // ---- THE collision: a character arrives while the slot is full ----
        base_got = n_got; base_over = n_over;
        offer(8'h42);                       // fills the slot
        offer(8'h43);                       // collides: policy drops 0x43
        settle;
        check(n_over == base_over + 1, "collision: exactly one overrun event");
        check(data_valid === 1'b1,    "collision: slot still full");
        check(data === 8'h42,         "collision: the HELD byte survives");
        @(negedge clk) data_ready = 1'b1;
        @(negedge clk) data_ready = 1'b0;
        @(negedge clk);
        check(got[n_got-1] == 8'h42,  "collision: 0x42 delivered, 0x43 lost");

        // ---- the same-cycle hand-off must NOT be an overrun ---------------
        // Slot full, consumer asserting ready, a new character arriving on
        // the same clock: the slot is emptied and refilled in one cycle.
        base_over = n_over;
        offer(8'h44);
        @(negedge clk) data_ready = 1'b1; rx_char_data = 8'h45; rx_char_valid = 1'b1;
        @(negedge clk) data_ready = 1'b0; rx_char_valid = 1'b0;
        @(negedge clk);
        check(n_over == base_over,  "same-cycle handoff raises no overrun");
        check(data_valid === 1'b1,  "same-cycle handoff: slot refilled");
        check(data === 8'h45,       "same-cycle handoff: new byte held");
        @(negedge clk) data_ready = 1'b1;
        @(negedge clk) data_ready = 1'b0;
        @(negedge clk);

        // ---- sustained traffic with a keeping-up consumer -----------------
        base_got = n_got; base_over = n_over;
        data_ready = 1'b1;
        for (i = 0; i < 8; i = i + 1) begin
            @(negedge clk) rx_char_data = 8'h50 + i[7:0]; rx_char_valid = 1'b1;
            @(negedge clk) rx_char_valid = 1'b0;
        end
        repeat (4) @(negedge clk);
        data_ready = 1'b0;
        settle;
        check(n_over == base_over,     "consumer keeping up: no overrun at all");
        check(n_got == base_got + 8,   "consumer keeping up: all 8 delivered");
        check(got[n_got-1] == 8'h57,   "last delivered byte is the last sent");

        // ---- sustained traffic with a consumer that never reads ----------
        base_got = n_got; base_over = n_over;
        for (i = 0; i < 5; i = i + 1) offer(8'h60 + i[7:0]);
        settle;
        check(n_got == base_got,       "consumer asleep: nothing delivered");
        check(n_over == base_over + 4, "consumer asleep: 4 of 5 dropped");
        check(data === 8'h60,          "consumer asleep: the FIRST byte is the one kept");

        // ---- reset while full ---------------------------------------------
        @(negedge clk) rst_n = 1'b0;
        repeat (2) @(negedge clk);
        check(data_valid === 1'b0, "reset while full: slot empties");
        @(negedge clk) rst_n = 1'b1;
        @(negedge clk);

        check(over_wide == 0, "overrun event never wider than one clock");

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

//===========================================================================
//  tb_uart_rx_holding_sv — self-checking Verilog-2001 testbench
//
//  INDEPENDENCE: the checker keeps its own model of what SHOULD have reached
//  the consumer — a queue of the bytes the stimulus offered, minus the ones
//  the policy says were dropped — and compares that sequence against what
//  actually came out. It never inspects data_valid_o to decide what the
//  policy was; it decides from the stimulus it drove.
//
//  The POLICY under test (an architecture choice, not a UART rule): on a
//  collision the HELD byte survives and the NEW one is lost.
//===========================================================================
`timescale 1ns/1ps

module tb_uart_rx_holding_sv;

    localparam DATA_W = 8;

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

    logic            rx_char_valid = 1'b0;
    logic[DATA_W-1:0] rx_char_data = 8'h00;
    logic            data_ready    = 1'b0;
    logic [DATA_W-1:0] data;
    logic             data_valid, overrun_evt;

    uart_rx_holding #(.DATA_W(DATA_W)) dut (
        .clk(clk), .rst_n(rst_n),
        .rx_char_valid_i(rx_char_valid), .rx_char_data_i(rx_char_data),
        .data_o(data), .data_valid_o(data_valid), .data_ready_i(data_ready),
        .overrun_evt_o(overrun_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 observation of what the consumer actually received --
    logic [DATA_W-1:0] got [0:63];
    int n_got = 0, n_over = 0, over_wide = 0;
    logic over_prev = 1'b0;

    always @(posedge clk) if (rst_n) begin
        if (data_valid && data_ready) begin
            got[n_got] = data;
            n_got = n_got + 1;
        end
        if (overrun_evt) begin
            n_over = n_over + 1;
            if (over_prev) over_wide = over_wide + 1;
        end
        over_prev = overrun_evt;
    end

    task offer;                 // one-cycle arrival of a character
        input [DATA_W-1:0] d;
        begin
            @(negedge clk) rx_char_data = d; rx_char_valid = 1'b1;
            @(negedge clk) rx_char_valid = 1'b0;
        end
    endtask

    // overrun_evt_o is registered, and the observer samples a registered
    // output, so an event is two active edges behind the stimulus that
    // caused it. Counts are only meaningful after this settles -- reading
    // them earlier tests the testbench's timing, not the design's.
    task settle;
        begin repeat (2) @(negedge clk); end
    endtask

    int base_got, base_over, i;

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

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

        rst_n = 1'b0; data_ready = 1'b0;
        repeat (4) @(negedge clk);
        check(data_valid === 1'b0 && overrun_evt === 1'b0, "reset: empty, no overrun");
        @(negedge clk) rst_n = 1'b1;
        @(negedge clk);

        // ---- one character, then a consumer read --------------------------
        base_got = n_got; base_over = n_over;
        offer(8'h41);
        check(data_valid === 1'b1,   "first character: slot becomes full");
        check(data === 8'h41,        "first character: payload correct");
        check(n_over == base_over,   "first character: no overrun");
        @(negedge clk) data_ready = 1'b1;
        @(negedge clk) data_ready = 1'b0;
        @(negedge clk);
        check(data_valid === 1'b0,   "after the read: slot empties");
        check(n_got == base_got + 1, "after the read: one byte delivered");
        check(got[base_got] == 8'h41,"delivered byte is the one offered");

        // ---- THE collision: a character arrives while the slot is full ----
        base_got = n_got; base_over = n_over;
        offer(8'h42);                       // fills the slot
        offer(8'h43);                       // collides: policy drops 0x43
        settle();
        check(n_over == base_over + 1, "collision: exactly one overrun event");
        check(data_valid === 1'b1,    "collision: slot still full");
        check(data === 8'h42,         "collision: the HELD byte survives");
        @(negedge clk) data_ready = 1'b1;
        @(negedge clk) data_ready = 1'b0;
        @(negedge clk);
        check(got[n_got-1] == 8'h42,  "collision: 0x42 delivered, 0x43 lost");

        // ---- the same-cycle hand-off must NOT be an overrun ---------------
        // Slot full, consumer asserting ready, a new character arriving on
        // the same clock: the slot is emptied and refilled in one cycle.
        base_over = n_over;
        offer(8'h44);
        @(negedge clk) data_ready = 1'b1; rx_char_data = 8'h45; rx_char_valid = 1'b1;
        @(negedge clk) data_ready = 1'b0; rx_char_valid = 1'b0;
        @(negedge clk);
        check(n_over == base_over,  "same-cycle handoff raises no overrun");
        check(data_valid === 1'b1,  "same-cycle handoff: slot refilled");
        check(data === 8'h45,       "same-cycle handoff: new byte held");
        @(negedge clk) data_ready = 1'b1;
        @(negedge clk) data_ready = 1'b0;
        @(negedge clk);

        // ---- sustained traffic with a keeping-up consumer -----------------
        base_got = n_got; base_over = n_over;
        data_ready = 1'b1;
        for (i = 0; i < 8; i = i + 1) begin
            @(negedge clk) rx_char_data = 8'h50 + i[7:0]; rx_char_valid = 1'b1;
            @(negedge clk) rx_char_valid = 1'b0;
        end
        repeat (4) @(negedge clk);
        data_ready = 1'b0;
        settle();
        check(n_over == base_over,     "consumer keeping up: no overrun at all");
        check(n_got == base_got + 8,   "consumer keeping up: all 8 delivered");
        check(got[n_got-1] == 8'h57,   "last delivered byte is the last sent");

        // ---- sustained traffic with a consumer that never reads ----------
        base_got = n_got; base_over = n_over;
        for (i = 0; i < 5; i = i + 1) offer(8'h60 + i[7:0]);
        settle();
        check(n_got == base_got,       "consumer asleep: nothing delivered");
        check(n_over == base_over + 4, "consumer asleep: 4 of 5 dropped");
        check(data === 8'h60,          "consumer asleep: the FIRST byte is the one kept");

        // ---- reset while full ---------------------------------------------
        @(negedge clk) rst_n = 1'b0;
        repeat (2) @(negedge clk);
        check(data_valid === 1'b0, "reset while full: slot empties");
        @(negedge clk) rst_n = 1'b1;
        @(negedge clk);

        check(over_wide == 0, "overrun event never wider than one clock");

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

--==========================================================================
--  tb_uart_rx_holding -- self-checking VHDL-2008 testbench
--
--  Same 22 checks as the Verilog and SystemVerilog testbenches. The checker
--  records what the CONSUMER actually received and compares it against the
--  sequence the stimulus offered minus the bytes the policy drops; it never
--  decides the policy by looking at the DUT.
--==========================================================================
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;
use std.env.finish;

entity tb_uart_rx_holding is
end entity tb_uart_rx_holding;

architecture sim of tb_uart_rx_holding is

    constant DATA_W     : positive := 8;
    constant CLK_PERIOD : time     := 10 ns;

    signal clk   : std_logic := '0';
    signal rst_n : std_logic := '0';
    signal done  : std_logic := '0';

    signal rx_char_valid : std_logic := '0';
    signal rx_char_data  : std_logic_vector(DATA_W-1 downto 0) := (others => '0');
    signal data_ready    : std_logic := '0';
    signal data          : std_logic_vector(DATA_W-1 downto 0);
    signal data_valid    : std_logic;
    signal overrun_evt   : std_logic;

    type byte_arr is array (0 to 63) of std_logic_vector(DATA_W-1 downto 0);
    signal got       : byte_arr := (others => (others => '0'));
    signal n_got     : natural  := 0;
    signal n_over    : natural  := 0;
    signal over_wide : natural  := 0;

begin

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

    dut : entity work.uart_rx_holding
        generic map (DATA_W => DATA_W)
        port map (clk => clk, rst_n => rst_n,
                  rx_char_valid_i => rx_char_valid, rx_char_data_i => rx_char_data,
                  data_o => data, data_valid_o => data_valid,
                  data_ready_i => data_ready, overrun_evt_o => overrun_evt);

    obs : process (clk)
        variable g, o, w : natural := 0;
        variable prev    : std_logic := '0';
        variable arr     : byte_arr := (others => (others => '0'));
    begin
        if rising_edge(clk) and rst_n = '1' then
            if data_valid = '1' and data_ready = '1' then
                arr(g) := data;
                g := g + 1;
            end if;
            if overrun_evt = '1' then
                o := o + 1;
                if prev = '1' then w := w + 1; end if;
            end if;
            prev      := overrun_evt;
            got       <= arr;
            n_got     <= g;
            n_over    <= o;
            over_wide <= w;
        end if;
    end process obs;

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

    stim : process
        variable checks   : natural := 0;
        variable failures : natural := 0;
        variable base_got, base_over : 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 offer(d : std_logic_vector) is
        begin
            wait until falling_edge(clk); rx_char_data <= d; rx_char_valid <= '1';
            wait until falling_edge(clk); rx_char_valid <= '0';
        end procedure;

        -- overrun_evt_o is registered and the observer samples a registered
        -- output, so counts are two active edges behind their stimulus.
        procedure settle is
        begin
            for i in 0 to 1 loop wait until falling_edge(clk); end loop;
        end procedure;
    begin
        report "== uart_rx_holding (VHDL) : self-checking testbench ==";

        rst_n <= '0'; data_ready <= '0';
        for i in 0 to 3 loop wait until falling_edge(clk); end loop;
        check(data_valid = '0' and overrun_evt = '0', "reset: empty, no overrun");
        rst_n <= '1';
        wait until falling_edge(clk);

        base_got := n_got; base_over := n_over;
        offer(x"41");
        check(data_valid = '1',      "first character: slot becomes full");
        check(data = x"41",          "first character: payload correct");
        check(n_over = base_over,    "first character: no overrun");
        wait until falling_edge(clk); data_ready <= '1';
        wait until falling_edge(clk); data_ready <= '0';
        wait until falling_edge(clk);
        check(data_valid = '0',      "after the read: slot empties");
        check(n_got = base_got + 1,  "after the read: one byte delivered");
        check(got(base_got) = x"41", "delivered byte is the one offered");

        base_got := n_got; base_over := n_over;
        offer(x"42");
        offer(x"43");
        settle;
        check(n_over = base_over + 1, "collision: exactly one overrun event");
        check(data_valid = '1',       "collision: slot still full");
        check(data = x"42",           "collision: the HELD byte survives");
        wait until falling_edge(clk); data_ready <= '1';
        wait until falling_edge(clk); data_ready <= '0';
        wait until falling_edge(clk);
        check(got(n_got-1) = x"42",   "collision: 0x42 delivered, 0x43 lost");

        base_over := n_over;
        offer(x"44");
        wait until falling_edge(clk); data_ready <= '1'; rx_char_data <= x"45"; rx_char_valid <= '1';
        wait until falling_edge(clk); data_ready <= '0'; rx_char_valid <= '0';
        wait until falling_edge(clk);
        check(n_over = base_over,   "same-cycle handoff raises no overrun");
        check(data_valid = '1',     "same-cycle handoff: slot refilled");
        check(data = x"45",         "same-cycle handoff: new byte held");
        wait until falling_edge(clk); data_ready <= '1';
        wait until falling_edge(clk); data_ready <= '0';
        wait until falling_edge(clk);

        base_got := n_got; base_over := n_over;
        data_ready <= '1';
        for i in 0 to 7 loop
            wait until falling_edge(clk);
            rx_char_data <= std_logic_vector(to_unsigned(16#50# + i, DATA_W));
            rx_char_valid <= '1';
            wait until falling_edge(clk); rx_char_valid <= '0';
        end loop;
        for i in 0 to 3 loop wait until falling_edge(clk); end loop;
        data_ready <= '0';
        settle;
        check(n_over = base_over,      "consumer keeping up: no overrun at all");
        check(n_got = base_got + 8,    "consumer keeping up: all 8 delivered");
        check(got(n_got-1) = x"57",    "last delivered byte is the last sent");

        base_got := n_got; base_over := n_over;
        for i in 0 to 4 loop
            offer(std_logic_vector(to_unsigned(16#60# + i, DATA_W)));
        end loop;
        settle;
        check(n_got = base_got,        "consumer asleep: nothing delivered");
        check(n_over = base_over + 4,  "consumer asleep: 4 of 5 dropped");
        check(data = x"60",            "consumer asleep: the FIRST byte is the one kept");

        wait until falling_edge(clk); rst_n <= '0';
        for i in 0 to 1 loop wait until falling_edge(clk); end loop;
        check(data_valid = '0', "reset while full: slot empties");
        wait until falling_edge(clk); rst_n <= '1';
        wait until falling_edge(clk);

        check(over_wide = 0, "overrun event never wider than one clock");

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

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

end architecture sim;

$ iverilog -g2001 -o sim uart_rx_holding_v.v tb_uart_rx_holding_v.v && ./sim
  PASS first character: slot becomes full
  PASS collision: exactly one overrun event
  PASS collision: the HELD byte survives
  PASS collision: 0x42 delivered, 0x43 lost
  PASS same-cycle handoff raises no overrun
  PASS consumer keeping up: no overrun at all
  PASS consumer keeping up: all 8 delivered
  PASS consumer asleep: 4 of 5 dropped
  PASS consumer asleep: the FIRST byte is the one kept
  PASS reset while full: slot empties
  PASS overrun event never wider than one clock
== 22 checks, 0 failures ==
   RESULT: ALL VERILOG HOLDING TESTS PASSED

protocol violation      : a byte the far end sent was destroyed  (receive overrun)
system availability     : a byte our own producer failed to supply (transmit starvation)

// Assertion — an overrun is reported ONLY when the slot was genuinely
// unavailable. This is the positive control expressed formally.
property p_overrun_only_when_blocked;
    @(posedge clk) disable iff (!rst_n)
        overrun_evt_o |-> $past(rx_char_valid_i && data_valid_o && !data_ready_i);
endproperty
assert property (p_overrun_only_when_blocked);

// Assertion — the held byte is never disturbed by an overrun.
// This is the retention policy, stated as a property.
property p_overrun_preserves_data;
    @(posedge clk) disable iff (!rst_n)
        overrun_evt_o |-> $stable(data_o);
endproperty
assert property (p_overrun_preserves_data);

// Assertion — a character arriving into a free slot is always stored.
// Nothing accepted may be silently dropped.
property p_free_slot_always_stores;
    @(posedge clk) disable iff (!rst_n)
        (rx_char_valid_i && (!data_valid_o || data_ready_i)) |=> data_valid_o;
endproperty
assert property (p_free_slot_always_stores);