Bit Ordering — MSB-First and LSB-First

// spi_bitorder.sv — a transfer engine whose bit order is configurable.
//
// Bit order costs exactly two multiplexers: one choosing which END of the
// transmit register feeds the pin, and one choosing which DIRECTION each
// register shifts. Everything else is Chapter 4.2's engine unchanged.
module spi_bitorder #(
    parameter int WIDTH = 8
) (
    input  logic             clk,
    input  logic             rst_n,
    input  logic             cs_n,
    input  logic             launch_stb,
    input  logic             sample_stb,
    input  logic             msb_first,   // 1 = MSB-first, 0 = LSB-first
    input  logic [WIDTH-1:0] tx_data,
    input  logic             sdi,
    output logic             sdo,
    output logic [WIDTH-1:0] rx_data,
    output logic             done
);
    localparam int CW = (WIDTH > 1) ? $clog2(WIDTH) : 1;

    logic [WIDTH-1:0] tx_sh, rx_sh, rx_next;
    logic [CW-1:0]    bit_cnt;
    logic             cs_n_q;

    // The receive register fills from the opposite end it empties toward, so
    // the first bit in ends up where the first bit out came from.
    assign rx_next = msb_first ? {rx_sh[WIDTH-2:0], sdi}    // in at the bottom
                               : {sdi, rx_sh[WIDTH-1:1]};   // in at the top

    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            tx_sh   <= '0;
            rx_sh   <= '0;
            bit_cnt <= '0;
            rx_data <= '0;
            done    <= 1'b0;
            cs_n_q  <= 1'b1;
        end else begin
            cs_n_q <= cs_n;
            done   <= 1'b0;

            if (cs_n) begin
                tx_sh   <= tx_data;
                bit_cnt <= '0;
            end else begin
                if (cs_n_q) begin
                    tx_sh   <= tx_data;
                    bit_cnt <= '0;
                end
                if (sample_stb) begin
                    rx_sh <= rx_next;
                    if (bit_cnt == CW'(WIDTH - 1)) begin
                        bit_cnt <= '0;
                        rx_data <= rx_next;
                        done    <= 1'b1;
                    end else begin
                        bit_cnt <= bit_cnt + 1'b1;
                    end
                end
                if (launch_stb)
                    tx_sh <= msb_first ? {tx_sh[WIDTH-2:0], 1'b0}   // shift left
                                       : {1'b0, tx_sh[WIDTH-1:1]};  // shift right
            end
        end
    end

    // The output tap follows the shift direction: the bit about to leave.
    assign sdo = msb_first ? tx_sh[WIDTH-1] : tx_sh[0];
endmodule

// spi_bitorder_tb.sv — both orders, and the values that HIDE an order bug.
`timescale 1ns/1ps
module spi_bitorder_tb;
    logic clk = 0, rst_n = 0;
    always #5 clk = ~clk;

    localparam int W = 8;
    logic cs_n = 1, launch = 0, sample = 0, sdi = 0, msb_first = 1;
    logic [W-1:0] tx_data;
    logic sdo; logic [W-1:0] rx_data; logic done;

    spi_bitorder #(.WIDTH(W)) dut (.clk, .rst_n, .cs_n, .launch_stb(launch), .sample_stb(sample),
                                   .msb_first, .tx_data, .sdi, .sdo, .rx_data, .done);

    int errors = 0;
    task automatic chk(input string what, input int got, input int exp);
        if (got !== exp) begin $display("FAIL %s: got 0x%0h exp 0x%0h", what, got, exp); errors++; end
    endtask

    function automatic logic [W-1:0] reverse(input logic [W-1:0] v);
        for (int i = 0; i < W; i++) reverse[i] = v[W-1-i];
    endfunction

    // Drive one bit time and collect sdo (sampled before the launch edge).
    logic [W-1:0] got_sdo;

    // Values whose bit-reversal equals themselves. MSB-first and LSB-first
    // produce IDENTICAL wire patterns for each, so a suite built only from
    // them passes with the bit order wired backwards.
    logic [W-1:0] blind [4] = '{8'h00, 8'hFF, 8'hA5, 8'h18};
    task automatic run_frame(input logic [W-1:0] din);
        got_sdo = '0;
        cs_n = 0; @(negedge clk);
        for (int i = 0; i < W; i++) begin
            got_sdo = {got_sdo[W-2:0], sdo};
            sdi = din[W-1-i];                       // feed MSB-first on the wire
            @(negedge clk); sample = 1; @(negedge clk); sample = 0;
            @(negedge clk); launch = 1; @(negedge clk); launch = 0;
        end
        cs_n = 1; @(negedge clk);
    endtask

    initial begin
        repeat (3) @(negedge clk); rst_n = 1; @(negedge clk);

        // --- MSB-first: the wire carries the word as written ---
        msb_first = 1; tx_data = 8'h2C;
        run_frame(8'h9B);
        chk("MSB-first sdo", got_sdo, 8'h2C);
        chk("MSB-first rx",  rx_data, 8'h9B);

        // --- LSB-first: the wire carries the word bit-reversed ---
        msb_first = 0; tx_data = 8'h2C;
        run_frame(8'h9B);
        chk("LSB-first sdo", got_sdo, reverse(8'h2C));   // 0x2C -> 0x34
        chk("LSB-first rx",  rx_data, reverse(8'h9B));   // 0x9B -> 0xD9

        // --- The values that HIDE the bug. For each of these, MSB-first and
        //     LSB-first produce IDENTICAL wire patterns, so a test using only
        //     them passes with the order wired backwards. This is the point
        //     of the chapter, asserted rather than asserted-about. ---
        begin
            foreach (blind[k]) begin
                logic [W-1:0] wire_msb, wire_lsb;
                msb_first = 1; tx_data = blind[k]; run_frame(8'h00); wire_msb = got_sdo;
                msb_first = 0; tx_data = blind[k]; run_frame(8'h00); wire_lsb = got_sdo;
                chk($sformatf("blind value 0x%02h is a palindrome", blind[k]), wire_lsb, wire_msb);
            end
        end

        if (errors == 0)
            $display("PASS: both orders transmit and receive correctly; the four palindromic values produce identical wire patterns in both orders");
        else
            $display("FAILED with %0d error(s)", errors);
        $finish;
    end

    initial begin #200000; $display("FAIL: watchdog timeout"); $finish; end
endmodule

// spi_bitorder.v — the same configurable-order engine in Verilog-2001.
module spi_bitorder #(
    parameter WIDTH = 8
) (
    input  wire             clk,
    input  wire             rst_n,
    input  wire             cs_n,
    input  wire             launch_stb,
    input  wire             sample_stb,
    input  wire             msb_first,
    input  wire [WIDTH-1:0] tx_data,
    input  wire             sdi,
    output wire             sdo,
    output reg  [WIDTH-1:0] rx_data,
    output reg              done
);
    function integer clogb2;
        input integer value;
        integer v;
        begin
            v = value - 1;
            for (clogb2 = 0; v > 0; clogb2 = clogb2 + 1) v = v >> 1;
        end
    endfunction

    localparam CW = (WIDTH > 1) ? clogb2(WIDTH) : 1;

    reg  [WIDTH-1:0] tx_sh, rx_sh;
    reg  [CW-1:0]    bit_cnt;
    reg              cs_n_q;
    wire [WIDTH-1:0] rx_next;

    assign rx_next = msb_first ? {rx_sh[WIDTH-2:0], sdi}
                               : {sdi, rx_sh[WIDTH-1:1]};

    always @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            tx_sh   <= {WIDTH{1'b0}};
            rx_sh   <= {WIDTH{1'b0}};
            bit_cnt <= {CW{1'b0}};
            rx_data <= {WIDTH{1'b0}};
            done    <= 1'b0;
            cs_n_q  <= 1'b1;
        end else begin
            cs_n_q <= cs_n;
            done   <= 1'b0;

            if (cs_n) begin
                tx_sh   <= tx_data;
                bit_cnt <= {CW{1'b0}};
            end else begin
                if (cs_n_q) begin
                    tx_sh   <= tx_data;
                    bit_cnt <= {CW{1'b0}};
                end
                if (sample_stb) begin
                    rx_sh <= rx_next;
                    if (bit_cnt == (WIDTH - 1)) begin
                        bit_cnt <= {CW{1'b0}};
                        rx_data <= rx_next;
                        done    <= 1'b1;
                    end else begin
                        bit_cnt <= bit_cnt + 1'b1;
                    end
                end
                if (launch_stb)
                    tx_sh <= msb_first ? {tx_sh[WIDTH-2:0], 1'b0}
                                       : {1'b0, tx_sh[WIDTH-1:1]};
            end
        end
    end

    assign sdo = msb_first ? tx_sh[WIDTH-1] : tx_sh[0];
endmodule

// spi_bitorder_tb.v — the same checks in Verilog-2001.
`timescale 1ns/1ps
module spi_bitorder_tb;
    reg clk = 0, rst_n = 0;
    always #5 clk = ~clk;

    parameter W = 8;
    reg cs_n = 1, launch = 0, sample = 0, sdi = 0, msb_first = 1;
    reg  [W-1:0] tx_data;
    wire sdo; wire [W-1:0] rx_data; wire done;

    spi_bitorder #(.WIDTH(W)) dut (
        .clk(clk), .rst_n(rst_n), .cs_n(cs_n), .launch_stb(launch), .sample_stb(sample),
        .msb_first(msb_first), .tx_data(tx_data), .sdi(sdi), .sdo(sdo),
        .rx_data(rx_data), .done(done));

    integer errors = 0, i, k;
    reg [W-1:0] got_sdo, din_r, wire_msb, wire_lsb;

    // Values whose bit-reversal equals themselves: both orders look identical.
    reg [W-1:0] blind [0:3];
    initial begin
        blind[0] = 8'h00; blind[1] = 8'hFF; blind[2] = 8'hA5; blind[3] = 8'h18;
    end

    function [W-1:0] reverse;
        input [W-1:0] v;
        integer j;
        begin
            for (j = 0; j < W; j = j + 1) reverse[j] = v[W-1-j];
        end
    endfunction

    task chk;
        input [80*8-1:0] what;
        input [W-1:0] got, exp;
        begin
            if (got !== exp) begin
                $display("FAIL %0s: got 0x%0h exp 0x%0h", what, got, exp);
                errors = errors + 1;
            end
        end
    endtask

    task run_frame;
        input [W-1:0] din;
        begin
            got_sdo = {W{1'b0}};
            cs_n = 0; @(negedge clk);
            for (i = 0; i < W; i = i + 1) begin
                got_sdo = {got_sdo[W-2:0], sdo};
                sdi = din[W-1-i];
                @(negedge clk); sample = 1; @(negedge clk); sample = 0;
                @(negedge clk); launch = 1; @(negedge clk); launch = 0;
            end
            cs_n = 1; @(negedge clk);
        end
    endtask

    initial begin
        repeat (3) @(negedge clk); rst_n = 1; @(negedge clk);

        msb_first = 1; tx_data = 8'h2C; run_frame(8'h9B);
        chk("MSB-first sdo", got_sdo, 8'h2C);
        chk("MSB-first rx",  rx_data, 8'h9B);

        msb_first = 0; tx_data = 8'h2C; run_frame(8'h9B);
        chk("LSB-first sdo", got_sdo, reverse(8'h2C));
        chk("LSB-first rx",  rx_data, reverse(8'h9B));

        for (k = 0; k < 4; k = k + 1) begin
            msb_first = 1; tx_data = blind[k]; run_frame(8'h00); wire_msb = got_sdo;
            msb_first = 0; tx_data = blind[k]; run_frame(8'h00); wire_lsb = got_sdo;
            chk("blind palindromic value", wire_lsb, wire_msb);
        end

        if (errors == 0)
            $display("PASS: both orders transmit and receive correctly; the four palindromic values produce identical wire patterns in both orders");
        else
            $display("FAILED with %0d error(s)", errors);
        $finish;
    end

    initial begin #200000; $display("FAIL: watchdog timeout"); $finish; end
endmodule

-- spi_bitorder.vhd — the same configurable-order engine in VHDL.
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

entity spi_bitorder is
    generic (
        WIDTH : positive := 8
    );
    port (
        clk        : in  std_logic;
        rst_n      : in  std_logic;
        cs_n       : in  std_logic;
        launch_stb : in  std_logic;
        sample_stb : in  std_logic;
        msb_first  : in  std_logic;
        tx_data    : in  std_logic_vector(WIDTH - 1 downto 0);
        sdi        : in  std_logic;
        sdo        : out std_logic;
        rx_data    : out std_logic_vector(WIDTH - 1 downto 0);
        done       : out std_logic
    );
end entity spi_bitorder;

architecture rtl of spi_bitorder is
    signal bit_cnt : integer range 0 to WIDTH - 1;
    signal tx_sh   : std_logic_vector(WIDTH - 1 downto 0);
    signal rx_sh   : std_logic_vector(WIDTH - 1 downto 0);
    signal rx_next : std_logic_vector(WIDTH - 1 downto 0);
    signal cs_n_q  : std_logic;
begin

    -- The receive register fills from the end opposite the one it empties
    -- toward, so the first bit in lands where the first bit out came from.
    rx_next <= rx_sh(WIDTH - 2 downto 0) & sdi when msb_first = '1'
               else sdi & rx_sh(WIDTH - 1 downto 1);

    process (clk, rst_n) is
    begin
        if rst_n = '0' then
            tx_sh   <= (others => '0');
            rx_sh   <= (others => '0');
            bit_cnt <= 0;
            rx_data <= (others => '0');
            done    <= '0';
            cs_n_q  <= '1';
        elsif rising_edge(clk) then
            cs_n_q <= cs_n;
            done   <= '0';

            if cs_n = '1' then
                tx_sh   <= tx_data;
                bit_cnt <= 0;
            else
                if cs_n_q = '1' then
                    tx_sh   <= tx_data;
                    bit_cnt <= 0;
                end if;

                if sample_stb = '1' then
                    rx_sh <= rx_next;
                    if bit_cnt = WIDTH - 1 then
                        bit_cnt <= 0;
                        rx_data <= rx_next;
                        done    <= '1';
                    else
                        bit_cnt <= bit_cnt + 1;
                    end if;
                end if;

                if launch_stb = '1' then
                    if msb_first = '1' then
                        tx_sh <= tx_sh(WIDTH - 2 downto 0) & '0';   -- shift left
                    else
                        tx_sh <= '0' & tx_sh(WIDTH - 1 downto 1);   -- shift right
                    end if;
                end if;
            end if;
        end if;
    end process;

    -- The output tap follows the shift direction: the bit about to leave.
    sdo <= tx_sh(WIDTH - 1) when msb_first = '1' else tx_sh(0);

end architecture rtl;

-- spi_bitorder_tb.vhd — the same checks in VHDL.
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

entity spi_bitorder_tb is
end entity spi_bitorder_tb;

architecture tb of spi_bitorder_tb is
    constant W : positive := 8;

    signal clk       : std_logic := '0';
    signal rst_n     : std_logic := '0';
    signal cs_n      : std_logic := '1';
    signal launch    : std_logic := '0';
    signal sample    : std_logic := '0';
    signal sdi       : std_logic := '0';
    signal msb_first : std_logic := '1';
    signal halt      : boolean   := false;

    signal tx_data : std_logic_vector(W - 1 downto 0) := (others => '0');
    signal sdo     : std_logic;
    signal rx_data : std_logic_vector(W - 1 downto 0);
    signal done    : std_logic;

    signal errors  : natural := 0;
    signal got_sdo : std_logic_vector(W - 1 downto 0) := (others => '0');

    type blind_arr is array (0 to 3) of std_logic_vector(W - 1 downto 0);
    -- Values whose bit-reversal equals themselves: both orders look identical.
    constant BLIND : blind_arr := (x"00", x"FF", x"A5", x"18");

    function reverse (v : std_logic_vector) return std_logic_vector is
        variable r : std_logic_vector(v'range);
    begin
        for i in v'range loop
            r(v'high - i + v'low) := v(i);
        end loop;
        return r;
    end function;
begin

    clk <= not clk after 5 ns when not halt else '0';

    dut : entity work.spi_bitorder
        generic map (WIDTH => W)
        port map (clk => clk, rst_n => rst_n, cs_n => cs_n, launch_stb => launch,
                  sample_stb => sample, msb_first => msb_first, tx_data => tx_data,
                  sdi => sdi, sdo => sdo, rx_data => rx_data, done => done);

    stim : process is
        variable wire_msb : std_logic_vector(W - 1 downto 0);
        variable wire_lsb : std_logic_vector(W - 1 downto 0);

        procedure chk (what : string; got, exp : std_logic_vector) is
        begin
            if got /= exp then
                report "FAIL " & what & ": got 0x" & to_hstring(got)
                    & " exp 0x" & to_hstring(exp) severity error;
                errors <= errors + 1;
            end if;
        end procedure;

        procedure run_frame (din : std_logic_vector(W - 1 downto 0)) is
        begin
            got_sdo <= (others => '0');
            cs_n <= '0';
            wait until falling_edge(clk);
            for i in 0 to W - 1 loop
                got_sdo <= got_sdo(W - 2 downto 0) & sdo;
                sdi <= din(W - 1 - i);
                wait until falling_edge(clk); sample <= '1';
                wait until falling_edge(clk); sample <= '0';
                wait until falling_edge(clk); launch <= '1';
                wait until falling_edge(clk); launch <= '0';
            end loop;
            cs_n <= '1';
            wait until falling_edge(clk);
        end procedure;
    begin
        for i in 0 to 2 loop
            wait until falling_edge(clk);
        end loop;
        rst_n <= '1';
        wait until falling_edge(clk);

        msb_first <= '1'; tx_data <= x"2C";
        wait until falling_edge(clk);
        run_frame(x"9B");
        chk("MSB-first sdo", got_sdo, x"2C");
        chk("MSB-first rx",  rx_data, x"9B");

        msb_first <= '0'; tx_data <= x"2C";
        wait until falling_edge(clk);
        run_frame(x"9B");
        chk("LSB-first sdo", got_sdo, reverse(x"2C"));
        chk("LSB-first rx",  rx_data, reverse(x"9B"));

        for k in BLIND'range loop
            msb_first <= '1'; tx_data <= BLIND(k);
            wait until falling_edge(clk);
            run_frame(x"00");
            wire_msb := got_sdo;

            msb_first <= '0'; tx_data <= BLIND(k);
            wait until falling_edge(clk);
            run_frame(x"00");
            wire_lsb := got_sdo;

            chk("blind palindromic value", wire_lsb, wire_msb);
        end loop;

        wait until falling_edge(clk);
        if errors = 0 then
            report "PASS: both orders transmit and receive correctly; the four "
                 & "palindromic values produce identical wire patterns in both orders"
                 severity note;
        else
            report "FAILED with " & integer'image(errors) & " error(s)" severity error;
        end if;
        halt <= true;
        wait;
    end process;

    watchdog : process is
    begin
        wait for 200 us;
        if not halt then
            report "FAIL: watchdog timeout" severity failure;
        end if;
        wait;
    end process;

end architecture tb;

   // A mid-frame change produces a word that corresponds to NO bit order --
   // not a reversed word, a meaningless one. Worth catching at the source
   // rather than debugging from corrupted data.
   property p_order_stable_in_frame;
       @(posedge clk) disable iff (!rst_n)
           !cs_n |=> $stable(msb_first);
   endproperty

   a_order_stable : assert property (p_order_stable_in_frame)
       else $error("msb_first changed while CS was asserted");

   covergroup spi_bitorder_cg @(posedge transfer_done);
       cp_order : coverpoint cfg.msb_first { bins msb = {1}; bins lsb = {0}; }

       // The bug is only OBSERVABLE on data that is not its own reversal.
       // Covering "both orders ran" is not enough if every word was 0xA5.
       cp_asymmetric : coverpoint (tx_word != bit_reverse(tx_word)) {
           bins symmetric  = {0};    // the blind spot -- fine to hit, fatal to hit ONLY
           bins asymmetric = {1};    // the bin that can actually fail
       }

       x_order_asym : cross cp_order, cp_asymmetric;
   endgroup