lfsr.v

/**
 * Linear Feedback Shift Register (LFSR)
 * 
 * This module implements a Galois LFSR (Linear Feedback Shift Register) that
 * generates pseudo-random sequences. LFSRs are widely used in cryptography,
 * error detection/correction, and random number generation.
 * 
 * Key Features:
 * - Galois configuration: Feedback taps XOR with register bits
 * - Configurable taps: Programmable tap pattern via TAPS parameter
 * - Seed loading: Can load initial value (seed)
 * - Serial output: LSB provides serial bit stream
 * - Parallel output: Full register value available
 * 
 * LFSR Operation:
 * - Feedback calculation: XOR of all tapped bits
 * - Shift operation: Right shift, feedback enters at MSB
 * - Sequence generation: Produces pseudo-random sequence
 * - Maximum length: Sequence length = 2^WIDTH - 1 (if primitive polynomial)
 * 
 * Tap Configuration:
 * - TAPS parameter: Bit mask indicating which positions are tapped
 * - TAPS[i]=1: Bit i is included in feedback calculation
 * - TAPS[i]=0: Bit i is not included
 * - Default (8'b10111000): Taps at positions 7, 5, 4, 3
 * 
 * Galois vs Fibonacci:
 * - Galois (this implementation): Taps XOR with register bits
 * - Fibonacci: Taps XOR together, result feeds into LSB
 * - Galois is typically faster in hardware
 * 
 * Use Cases:
 * - Pseudo-random number generation
 * - Scrambling/descrambling
 * - CRC generation
 * - Built-in self-test (BIST)
 * - Cryptography
 * 
 * @param WIDTH Width of LFSR (default: 8 bits)
 *             Maximum sequence length = 2^WIDTH - 1
 * @param TAPS Tap pattern (default: 8'b10111000)
 *            Bit mask indicating feedback tap positions
 * 
 * @input clk Clock signal
 * @input rst_n Active-low reset signal
 * @input enable Enable signal (high to shift)
 * @input load Load enable (high to load seed)
 * @input seed[WIDTH-1:0] Initial seed value
 * @output lfsr_out[WIDTH-1:0] Full LFSR register value
 * @output bit_out Serial output bit (LSB)
 */
module lfsr #(
    parameter WIDTH = 8,
    parameter TAPS = 8'b10111000  // Default taps for 8-bit LFSR
)(
    input wire clk,
    input wire rst_n,
    input wire enable,
    input wire load,
    input wire [WIDTH-1:0] seed,
    output wire [WIDTH-1:0] lfsr_out,
    output wire bit_out
);

    reg [WIDTH-1:0] lfsr_reg;
    wire feedback;
    
    // Output assignments
    assign lfsr_out = lfsr_reg;
    assign bit_out = lfsr_reg[0];  // LSB is the output bit
    
    // ============================================================================
    // Feedback Calculation
    // ============================================================================
    // Calculate feedback based on taps
    // The feedback is the XOR of all tapped bits
    genvar i;
    generate
        if (WIDTH <= 8) begin: w8
            // ====================================================================
            // Width ≤ 8: Simple Feedback
            // ====================================================================
            // For widths ≤ 8, use TAPS directly
            // Feedback = XOR of (lfsr_reg & TAPS)
            // This XORs all bits where TAPS[i] = 1
            assign feedback = ^(lfsr_reg & TAPS);
        end else begin: wn
            // ====================================================================
            // Width > 8: Extended Feedback
            // ====================================================================
            // For widths > 8, extend tap pattern
            // Lower 8 bits use TAPS, MSB always included
            wire [WIDTH-1:0] masked_taps;
            for (i = 0; i < WIDTH; i = i + 1) begin: tap_gen
                assign masked_taps[i] = (i < 8) ? (TAPS[i] & lfsr_reg[i]) : 
                                       ((i == WIDTH-1) ? lfsr_reg[i] : 1'b0);
            end
            // XOR all masked tap bits
            assign feedback = ^masked_taps;
        end
    endgenerate
    
    // ============================================================================
    // LFSR Shift Logic
    // ============================================================================
    // Implements Galois LFSR: shift right, feedback enters at MSB
    always @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            // ====================================================================
            // Reset State
            // ====================================================================
            // Reset all bits to zero
            lfsr_reg <= {WIDTH{1'b0}};
        end else if (load) begin
            // ====================================================================
            // Load Seed
            // ====================================================================
            // Load initial seed value
            // This allows starting from a specific state
            lfsr_reg <= seed;
        end else if (enable) begin
            // ====================================================================
            // Galois LFSR Implementation
            // ====================================================================
            // Shift right and insert feedback at MSB
            // Format: {feedback_bit, existing_bits[WIDTH-1:1]}
            // LSB is shifted out (available at bit_out)
            lfsr_reg <= {feedback, lfsr_reg[WIDTH-1:1]};
        end
        // ========================================================================
        // Hold Mode
        // ========================================================================
        // When enable is low and load is low, register holds current value
        // (implicit: no assignment means value is maintained)
    end

endmodule