Source-Address Learning

// -----------------------------------------------------------------------
// maclearn_pkg -- shared types for source-address learning.
// -----------------------------------------------------------------------
package maclearn_pkg;
 
  // Why a frame was refused as evidence. Every refusal is one of these,
  // and each has a different operational meaning.
  typedef enum logic [2:0] {
    LE_OK           = 3'd0,  // eligible -- learn from it
    LE_BAD_FCS      = 3'd1,  // frame failed Chapter 7.3's check
    LE_RUNT         = 3'd2,  // shorter than 64 octets
    LE_GROUP_SRC    = 3'd3,  // I/G set in the SOURCE address
    LE_NULL_SRC     = 3'd4,  // all-zero source
    LE_RESERVED_SRC = 3'd5,  // a reserved group range, defensively
    LE_PORT_DOWN    = 3'd6   // ingress port not in a learning state
  } learn_elig_e;
 
  // What the store did with a learn request. The distinction between
  // INSERT, REFRESH and MOVE is the whole of this chapter's telemetry.
  typedef enum logic [2:0] {
    LR_INSERT   = 3'd0,  // new address, empty slot found
    LR_REFRESH  = 3'd1,  // known address, same port -- age reset only
    LR_MOVE     = 3'd2,  // known address, DIFFERENT port
    LR_EVICT    = 3'd3,  // new address, slot taken -- something displaced
    LR_REJECT   = 3'd4,  // refused -- rate limit or table full
    LR_NONE     = 3'd5
  } learn_result_e;
 
  localparam int ADDR_W = 48;
 
endpackage

// -----------------------------------------------------------------------
// source_address_learner -- applies the eligibility rules to one frame and
// emits at most one learn request.
//
// The rules are short and every one of them has been omitted by a real
// implementation at some point. Each omission puts a specific class of
// garbage into the forwarding table.
// -----------------------------------------------------------------------
module source_address_learner
  import maclearn_pkg::*;
#(
  parameter int PORT_BITS = 5,
  parameter int PORT_ID   = 0
)(
  input  logic                 clk,
  input  logic                 rst_n,
 
  // One pulse per received frame, with the frame's outcome already known
  // because this design is store-and-forward -- Chapter 12.1 Section 10.
  input  logic                 frame_valid,
  input  logic [ADDR_W-1:0]    frame_src,
  input  logic                 frame_bad_fcs,
  input  logic                 frame_runt,
  input  logic                 port_learning_enabled,
 
  output logic                 learn_valid,
  output logic [ADDR_W-1:0]    learn_addr,
  output logic [PORT_BITS-1:0] learn_port,
  output learn_elig_e          refusal
);
 
  // RULE 1. The I/G bit of the SOURCE address. A group address can never
  // legitimately be a source -- nothing transmits as a group. Learning it
  // puts a multicast address in the table, where a later DESTINATION
  // lookup for that same group address will HIT and forward a multicast
  // frame out one port instead of flooding it.
  logic src_is_group;
  assign src_is_group = frame_src[40];
 
  // RULE 2. The all-zero source. Not a legal address, and a common
  // signature of a malformed or truncated frame.
  logic src_is_null;
  assign src_is_null = (frame_src == '0);
 
  // RULE 3. Reserved group range 01-80-C2-00-00-00 .. 0F. Control frames
  // use these as DESTINATIONS; one appearing as a source is malformed.
  // Rule 1 already covers it -- this is defence in depth, because the
  // consequence of learning a control address is severe.
  logic src_is_reserved;
  assign src_is_reserved =
    (frame_src[47:8] == 40'h01_80_C2_00_00) && (frame_src[7:4] == 4'h0);
 
  always_comb begin
    learn_valid = 1'b0;
    refusal     = LE_OK;
 
    if (frame_valid) begin
      // RULE 4. A frame that failed its check sequence is not evidence of
      // anything -- the source address field itself may be the corrupted
      // part. Learning from it inserts a fictitious address that will
      // displace a real one.
      if (frame_bad_fcs)                 refusal = LE_BAD_FCS;
      else if (frame_runt)               refusal = LE_RUNT;
      else if (src_is_group)             refusal = LE_GROUP_SRC;
      else if (src_is_null)              refusal = LE_NULL_SRC;
      else if (src_is_reserved)          refusal = LE_RESERVED_SRC;
      else if (!port_learning_enabled)   refusal = LE_PORT_DOWN;
      else begin
        learn_valid = 1'b1;
      end
    end
  end
 
  assign learn_addr = frame_src;
  assign learn_port = PORT_BITS'(PORT_ID);
 
endmodule

// -----------------------------------------------------------------------
// learning_store -- a behavioural forwarding table: insert, refresh, move,
// lookup and age.
//
// DELIBERATELY NOT A REAL MAC TABLE. A production table is a CAM or a
// hashed set-associative structure with collision handling -- Chapter 12.5
// owns that entirely. What this module is for is the ENTRY: what a row has
// to carry, and why each field exists.
// -----------------------------------------------------------------------
module learning_store
  import maclearn_pkg::*;
#(
  parameter int N_ENTRIES = 8192,
  parameter int PORT_BITS = 5,
  parameter int AGE_W     = 9,      // 300 s at a 1 s tick needs 9 bits
  parameter int IDX_W     = 13      // $clog2(8192)
)(
  input  logic                 clk,
  input  logic                 rst_n,
 
  // Learn side.
  input  logic                 learn_valid,
  input  logic [ADDR_W-1:0]    learn_addr,
  input  logic [PORT_BITS-1:0] learn_port,
  output learn_result_e        learn_result,
  output logic [PORT_BITS-1:0] displaced_port,   // valid on LR_MOVE
 
  // Lookup side -- Chapter 12.3 consumes this.
  input  logic                 lookup_valid,
  input  logic [ADDR_W-1:0]    lookup_addr,
  output logic                 lookup_hit,
  output logic [PORT_BITS-1:0] lookup_port,
 
  // Ageing tick, one pulse per second.
  input  logic                 age_tick,
  input  logic [AGE_W-1:0]     age_limit,        // 300 by default
 
  output logic [IDX_W:0]       occupancy,
  output logic                 table_full
);
 
  // An entry. Five fields, and only the first two are about forwarding.
  typedef struct packed {
    logic                 valid;
    logic [ADDR_W-1:0]    addr;
    logic [PORT_BITS-1:0] port;
    logic [AGE_W-1:0]     age;     // seconds since last SOURCE sighting
    logic                 stat;    // statically configured -- never ages
  } entry_t;
 
  entry_t tbl [N_ENTRIES];
 
  // Behavioural associative search. A real table hashes; Chapter 12.5
  // explains why, and what a hash collision costs.
  function automatic logic [IDX_W:0] find(input logic [ADDR_W-1:0] a);
    find = {1'b1, {IDX_W{1'b0}}};              // MSB set == not found
    for (int i = 0; i < N_ENTRIES; i++)
      if (tbl[i].valid && (tbl[i].addr == a)) find = IDX_W'(i);
  endfunction
 
  function automatic logic [IDX_W:0] free_slot();
    free_slot = {1'b1, {IDX_W{1'b0}}};
    for (int i = N_ENTRIES-1; i >= 0; i--)
      if (!tbl[i].valid) free_slot = IDX_W'(i);
  endfunction
 
  logic [IDX_W:0] hit_idx, new_idx;
  logic [IDX_W:0] used;
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      for (int i = 0; i < N_ENTRIES; i++) tbl[i] <= '0;
      learn_result   <= LR_NONE;
      displaced_port <= '0;
    end else begin
      learn_result <= LR_NONE;
 
      // ---- Learn -------------------------------------------------------
      if (learn_valid) begin
        hit_idx = find(learn_addr);
 
        if (!hit_idx[IDX_W]) begin
          // The address is known. Two very different cases.
          if (tbl[hit_idx[IDX_W-1:0]].port == learn_port) begin
            // REFRESH. The station is where we thought. Reset the age --
            // and note that this is the ONLY thing that resets it.
            tbl[hit_idx[IDX_W-1:0]].age <= '0;
            learn_result <= LR_REFRESH;
          end else begin
            // MOVE. The station is somewhere else now, OR something is
            // claiming to be it, OR there is a loop. The table cannot
            // tell these apart -- Section 10.
            displaced_port <= tbl[hit_idx[IDX_W-1:0]].port;
            tbl[hit_idx[IDX_W-1:0]].port <= learn_port;
            tbl[hit_idx[IDX_W-1:0]].age  <= '0;
            learn_result <= LR_MOVE;
          end
        end else begin
          // Unknown address. Insert if there is room.
          new_idx = free_slot();
          if (!new_idx[IDX_W]) begin
            tbl[new_idx[IDX_W-1:0]].valid <= 1'b1;
            tbl[new_idx[IDX_W-1:0]].addr  <= learn_addr;
            tbl[new_idx[IDX_W-1:0]].port  <= learn_port;
            tbl[new_idx[IDX_W-1:0]].age   <= '0;
            tbl[new_idx[IDX_W-1:0]].stat  <= 1'b0;
            learn_result <= LR_INSERT;
          end else begin
            // Full. This design REFUSES rather than evicting a live
            // entry, so a flood of new addresses cannot displace the
            // stations that are actually communicating.
            learn_result <= LR_REJECT;
          end
        end
      end
 
      // ---- Age ---------------------------------------------------------
      // One second per tick, every entry. A statically configured entry
      // is exempt: it was asserted by an operator, not inferred.
      if (age_tick) begin
        for (int i = 0; i < N_ENTRIES; i++) begin
          if (tbl[i].valid && !tbl[i].stat) begin
            if (tbl[i].age >= age_limit) tbl[i].valid <= 1'b0;
            else                         tbl[i].age   <= tbl[i].age + 1'b1;
          end
        end
      end
    end
  end
 
  // ---- Lookup ---------------------------------------------------------
  // NOTE what is NOT here: a lookup does not touch the age field. A hit
  // is not evidence about the destination -- Section 8.
  always_comb begin
    logic [IDX_W:0] q;
    lookup_hit  = 1'b0;
    lookup_port = '0;
    if (lookup_valid) begin
      q = find(lookup_addr);
      if (!q[IDX_W]) begin
        lookup_hit  = 1'b1;
        lookup_port = tbl[q[IDX_W-1:0]].port;
      end
    end
  end
 
  always_comb begin
    used = '0;
    for (int i = 0; i < N_ENTRIES; i++) if (tbl[i].valid) used = used + 1'b1;
  end
  assign occupancy  = used;
  assign table_full = (used >= (IDX_W+1)'(N_ENTRIES));
 
endmodule

// -----------------------------------------------------------------------
// entry_age_manager -- generates the ageing tick and reports what ageing is
// actually doing, which is the number nobody looks at.
//
// The default is 300 s, from 802.1D. This module exists to make visible
// that the interval is a TRADE, not a constant, and to report which side
// of the trade the current setting is landing on.
// -----------------------------------------------------------------------
module entry_age_manager #(
  parameter int CLK_HZ    = 125_000_000,
  parameter int AGE_W     = 9,
  parameter int CNT_W     = 32
)(
  input  logic             clk,
  input  logic             rst_n,
 
  input  logic [AGE_W-1:0] age_limit,         // seconds, 300 by default
 
  output logic             age_tick,          // one pulse per second
 
  // Observability -- what ageing costs and what it is preventing.
  input  logic             entry_expired,     // pulse from the store
  input  logic             lookup_miss,       // pulse from the lookup
  input  logic             lookup_hit,
 
  output logic [CNT_W-1:0] c_expired,
  output logic [CNT_W-1:0] c_miss,
  output logic [CNT_W-1:0] c_hit,
  output logic             miss_rate_high,    // ageing may be too aggressive
  output logic             ageing_idle        // ageing may be too slow
);
 
  localparam int TICK_MAX = CLK_HZ - 1;
 
  logic [$clog2(CLK_HZ)-1:0] div_q;
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      div_q    <= '0;
      age_tick <= 1'b0;
    end else begin
      age_tick <= 1'b0;
      if (div_q == $clog2(CLK_HZ)'(TICK_MAX)) begin
        div_q    <= '0;
        age_tick <= 1'b1;
      end else begin
        div_q <= div_q + 1'b1;
      end
    end
  end
 
  logic [CNT_W-1:0] win_hit, win_miss, win_exp;
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      c_expired <= '0; c_miss <= '0; c_hit <= '0;
      win_hit   <= '0; win_miss <= '0; win_exp <= '0;
      miss_rate_high <= 1'b0;
      ageing_idle    <= 1'b0;
    end else begin
      if (entry_expired) begin
        if (!(&c_expired)) c_expired <= c_expired + 1'b1;
        win_exp <= win_exp + 1'b1;
      end
      if (lookup_miss) begin
        if (!(&c_miss)) c_miss <= c_miss + 1'b1;
        win_miss <= win_miss + 1'b1;
      end
      if (lookup_hit) begin
        if (!(&c_hit)) c_hit <= c_hit + 1'b1;
        win_hit <= win_hit + 1'b1;
      end
 
      // Evaluate once a second, on the same tick that ages the table.
      if (age_tick) begin
        // MORE THAN A TENTH OF LOOKUPS MISSING is not normal steady-state
        // behaviour. In a stable network almost every destination is
        // known, and a high miss rate with a non-full table means entries
        // are expiring faster than their stations transmit.
        miss_rate_high <= (win_miss > (win_hit >> 3)) &&
                          (win_miss > CNT_W'(100));
 
        // Expiries at zero over a long period with a filling table means
        // the interval is longer than anything ever goes quiet for --
        // stale entries will accumulate until the table is full.
        ageing_idle    <= (win_exp == '0) && (win_hit > CNT_W'(10_000));
 
        win_hit <= '0; win_miss <= '0; win_exp <= '0;
      end
    end
  end
 
  // Unused in this reduced module, kept to document the interface.
  wire _unused_age_limit = |age_limit;
 
endmodule

// -----------------------------------------------------------------------
// station_move_detector -- watches LR_MOVE events and separates the three
// causes that produce them, which the store itself cannot distinguish.
//
// A legitimate move happens ONCE. A duplicate address alternates between
// two ports at the rate the two stations transmit. A loop alternates at
// close to line rate.
// -----------------------------------------------------------------------
module station_move_detector
  import maclearn_pkg::*;
#(
  parameter int PORT_BITS  = 5,
  parameter int CNT_W      = 32,
  parameter int FLAP_LIMIT = 10        // moves per second before it is a flap
)(
  input  logic                 clk,
  input  logic                 rst_n,
 
  input  logic                 learn_done,
  input  learn_result_e        learn_result,
  input  logic [ADDR_W-1:0]    learn_addr,
  input  logic [PORT_BITS-1:0] learn_port,
  input  logic [PORT_BITS-1:0] displaced_port,
  input  logic                 second_tick,
 
  output logic [CNT_W-1:0]     c_moves,
  output logic [ADDR_W-1:0]    last_moved_addr,
  output logic [PORT_BITS-1:0] last_moved_from,
  output logic [PORT_BITS-1:0] last_moved_to,
 
  output logic                 flapping,        // >FLAP_LIMIT moves in 1 s
  output logic [ADDR_W-1:0]    flapping_addr,
  output logic [1:0]           likely_cause     // 0 none 1 move 2 dup 3 loop
);
 
  logic [CNT_W-1:0] moves_this_second;
  logic [ADDR_W-1:0] watch_addr;
  logic [CNT_W-1:0]  watch_moves;
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      c_moves           <= '0;
      moves_this_second <= '0;
      watch_addr        <= '0;
      watch_moves       <= '0;
      last_moved_addr   <= '0;
      last_moved_from   <= '0;
      last_moved_to     <= '0;
      flapping          <= 1'b0;
      flapping_addr     <= '0;
      likely_cause      <= 2'd0;
    end else begin
      if (learn_done && (learn_result == LR_MOVE)) begin
        if (!(&c_moves)) c_moves <= c_moves + 1'b1;
        last_moved_addr <= learn_addr;
        last_moved_from <= displaced_port;
        last_moved_to   <= learn_port;
        moves_this_second <= moves_this_second + 1'b1;
 
        // Track ONE address at a time. Which address is flapping matters
        // far more than how many are, because one flapping address is a
        // duplicate and many at once is a loop.
        if (learn_addr == watch_addr) watch_moves <= watch_moves + 1'b1;
        else begin
          watch_addr  <= learn_addr;
          watch_moves <= CNT_W'(1);
        end
      end
 
      if (second_tick) begin
        flapping <= (moves_this_second > CNT_W'(FLAP_LIMIT));
        if (moves_this_second > CNT_W'(FLAP_LIMIT)) flapping_addr <= watch_addr;
 
        // The rate discriminates the cause. Below the flap limit, a move
        // is a move. A handful per second on ONE address is two stations
        // sharing it. Thousands per second, or many addresses at once,
        // is a topology loop -- the same frames arriving from two
        // directions.
        if (moves_this_second == '0)
          likely_cause <= 2'd0;
        else if (moves_this_second <= CNT_W'(FLAP_LIMIT))
          likely_cause <= 2'd1;                      // a real move
        else if (watch_moves > (moves_this_second >> 1))
          likely_cause <= 2'd2;                      // one address, duplicate
        else
          likely_cause <= 2'd3;                      // many addresses, loop
 
        moves_this_second <= '0;
        watch_moves       <= '0;
      end
    end
  end
 
endmodule

// -----------------------------------------------------------------------
// learning_rate_limiter -- caps NEW address insertions per port per second.
//
// This does not verify anything. Nothing can. What it does is make the
// arithmetic in Section 12 come out the other way: with a low enough cap,
// ageing reclaims entries faster than a single port can create them, so
// the table cannot be filled from one port no matter how long the attempt
// runs.
// -----------------------------------------------------------------------
module learning_rate_limiter
  import maclearn_pkg::*;
#(
  parameter int PORT_BITS   = 5,
  parameter int N_PORTS     = 24,
  parameter int NEW_PER_SEC = 25,     // derived in Section 12
  parameter int CNT_W       = 32
)(
  input  logic                 clk,
  input  logic                 rst_n,
 
  input  logic                 learn_req,
  input  logic [PORT_BITS-1:0] learn_port,
  input  logic                 addr_is_known,   // a refresh or a move
  input  logic                 second_tick,
 
  output logic                 learn_permit,
  output logic [CNT_W-1:0]     c_limited,
  output logic [PORT_BITS-1:0] worst_port,
  output logic                 limit_engaged
);
 
  // Budget is per PORT. A shared budget would let one abusive port starve
  // every other port's legitimate learning, which is exactly the
  // head-of-line pathology Chapter 12.1 Section 6 rejected for congestion.
  logic [CNT_W-1:0] new_this_second [N_PORTS];
  logic [CNT_W-1:0] limited_by_port [N_PORTS];
 
  // A KNOWN address is always permitted: refreshes and moves do not
  // consume table capacity, so limiting them would break real traffic
  // while doing nothing about the attack.
  always_comb begin
    learn_permit = 1'b0;
    if (learn_req) begin
      if (addr_is_known)
        learn_permit = 1'b1;
      else
        learn_permit = (new_this_second[learn_port] < CNT_W'(NEW_PER_SEC));
    end
  end
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      for (int p = 0; p < N_PORTS; p++) begin
        new_this_second[p] <= '0;
        limited_by_port[p] <= '0;
      end
      c_limited     <= '0;
      worst_port    <= '0;
      limit_engaged <= 1'b0;
    end else begin
      if (learn_req && !addr_is_known) begin
        if (learn_permit) begin
          new_this_second[learn_port] <= new_this_second[learn_port] + 1'b1;
        end else begin
          if (!(&c_limited)) c_limited <= c_limited + 1'b1;
          limited_by_port[learn_port] <= limited_by_port[learn_port] + 1'b1;
        end
      end
 
      if (second_tick) begin
        automatic logic [CNT_W-1:0] hi = '0;
        automatic logic [PORT_BITS-1:0] hp = '0;
        for (int p = 0; p < N_PORTS; p++) begin
          if (limited_by_port[p] > hi) begin
            hi = limited_by_port[p];
            hp = PORT_BITS'(p);
          end
          new_this_second[p] <= '0;
        end
        worst_port    <= hp;
        limit_engaged <= (hi != '0);
      end
    end
  end
 
endmodule

// -----------------------------------------------------------------------
// learn_evidence_recorder -- per-entry provenance.
//
// The forwarding path does not need any of this. It exists so that when an
// entry turns out to be wrong, there is a record of what produced it. An
// entry refreshed ten thousand times from one port over an hour and an
// entry inserted once, forty seconds ago, from a port that has moved it
// three times are both just "S is on P" to the lookup.
// -----------------------------------------------------------------------
module learn_evidence_recorder
  import maclearn_pkg::*;
#(
  parameter int PORT_BITS = 5,
  parameter int IDX_W     = 13,
  parameter int CNT_W     = 24,
  parameter int T_W       = 32
)(
  input  logic                 clk,
  input  logic                 rst_n,
 
  input  logic                 second_tick,
  input  logic                 learn_done,
  input  learn_result_e        learn_result,
  input  logic [IDX_W-1:0]     learn_index,
  input  logic [PORT_BITS-1:0] learn_port,
  input  logic                 entry_expired,
  input  logic [IDX_W-1:0]     expired_index,
 
  // Query one entry's provenance.
  input  logic                 query_valid,
  input  logic [IDX_W-1:0]     query_index,
  output logic [T_W-1:0]       q_first_seen_s,   // when first inserted
  output logic [T_W-1:0]       q_last_seen_s,    // when last refreshed
  output logic [CNT_W-1:0]     q_refreshes,      // how much evidence
  output logic [CNT_W-1:0]     q_moves,          // how unstable
  output logic [1:0]           q_confidence      // 0 none 1 weak 2 ok 3 strong
);
 
  localparam int N = 1 << IDX_W;
 
  logic [T_W-1:0]   uptime_s;
  logic [T_W-1:0]   first_seen [N];
  logic [T_W-1:0]   last_seen  [N];
  logic [CNT_W-1:0] refreshes  [N];
  logic [CNT_W-1:0] moves      [N];
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      uptime_s <= '0;
      for (int i = 0; i < N; i++) begin
        first_seen[i] <= '0; last_seen[i] <= '0;
        refreshes[i]  <= '0; moves[i]     <= '0;
      end
    end else begin
      if (second_tick) uptime_s <= uptime_s + 1'b1;
 
      if (learn_done) begin
        unique case (learn_result)
          LR_INSERT: begin
            // A fresh entry starts with NO history. Its provenance is
            // reset, not inherited from whatever occupied the slot.
            first_seen[learn_index] <= uptime_s;
            last_seen [learn_index] <= uptime_s;
            refreshes [learn_index] <= '0;
            moves     [learn_index] <= '0;
          end
          LR_REFRESH: begin
            last_seen[learn_index] <= uptime_s;
            if (!(&refreshes[learn_index]))
              refreshes[learn_index] <= refreshes[learn_index] + 1'b1;
          end
          LR_MOVE: begin
            last_seen[learn_index] <= uptime_s;
            if (!(&moves[learn_index]))
              moves[learn_index] <= moves[learn_index] + 1'b1;
          end
          default: ;
        endcase
      end
 
      // An expiry CLEARS the provenance. If the address is learned again
      // it is a new claim, not the continuation of an old one -- the same
      // epoch discipline Chapter 11.3 established for bring-up
      // measurements.
      if (entry_expired) begin
        first_seen[expired_index] <= '0;
        last_seen [expired_index] <= '0;
        refreshes [expired_index] <= '0;
        moves     [expired_index] <= '0;
      end
    end
  end
 
  always_comb begin
    q_first_seen_s = '0; q_last_seen_s = '0;
    q_refreshes    = '0; q_moves       = '0;
    q_confidence   = 2'd0;
 
    if (query_valid) begin
      q_first_seen_s = first_seen[query_index];
      q_last_seen_s  = last_seen [query_index];
      q_refreshes    = refreshes [query_index];
      q_moves        = moves     [query_index];
 
      // Confidence is a function of how much evidence there is and how
      // consistent it has been. It is advisory -- the forwarding path
      // ignores it entirely -- but it is what turns a table dump into a
      // diagnosis.
      if (q_moves > CNT_W'(3))                  q_confidence = 2'd1; // weak
      else if (q_refreshes > CNT_W'(1000))      q_confidence = 2'd3; // strong
      else if (q_refreshes > CNT_W'(10))        q_confidence = 2'd2; // ok
      else                                      q_confidence = 2'd1;
    end
  end
 
  wire _unused_port = |learn_port;
 
endmodule

// -----------------------------------------------------------------------
// learning_conformance_monitor -- checks the learning RULE against the
// frames that produced it.
//
// What it CAN check: that every eligible frame produced exactly one learn
// of its own source at its own ingress port; that no ineligible frame
// produced any learn; that a lookup never refreshed an age; that expiry
// happened at the configured interval and not before.
//
// What it CANNOT check, ever: whether the station whose address was
// learned is actually there. No signal in this design carries that fact,
// because no frame carries it.
// -----------------------------------------------------------------------
module learning_conformance_monitor
  import maclearn_pkg::*;
#(
  parameter int PORT_BITS = 5,
  parameter int AGE_W     = 9,
  parameter int CNT_W     = 32
)(
  input  logic                 clk,
  input  logic                 rst_n,
 
  input  logic                 frame_valid,
  input  logic [ADDR_W-1:0]    frame_src,
  input  logic [PORT_BITS-1:0] frame_ingress,
  input  logic                 frame_eligible,
 
  input  logic                 learn_valid,
  input  logic [ADDR_W-1:0]    learn_addr,
  input  logic [PORT_BITS-1:0] learn_port,
 
  input  logic                 lookup_valid,
  input  logic                 age_written,        // any age field changed
  input  logic                 learn_in_progress,
 
  input  logic                 entry_expired,
  input  logic [AGE_W-1:0]     expired_age,
  input  logic [AGE_W-1:0]     age_limit,
 
  output logic [CNT_W-1:0]     v_missing_learn,    // eligible, none emitted
  output logic [CNT_W-1:0]     v_spurious_learn,   // ineligible, one emitted
  output logic [CNT_W-1:0]     v_wrong_addr,
  output logic [CNT_W-1:0]     v_wrong_port,
  output logic [CNT_W-1:0]     v_lookup_refreshed, // the Section 8 bug
  output logic [CNT_W-1:0]     v_early_expiry,
  output logic                 conformant
);
 
  logic                 pend_q;
  logic [ADDR_W-1:0]    pend_src;
  logic [PORT_BITS-1:0] pend_port;
  logic                 pend_elig;
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      pend_q <= 1'b0; pend_src <= '0; pend_port <= '0; pend_elig <= 1'b0;
      v_missing_learn    <= '0;
      v_spurious_learn   <= '0;
      v_wrong_addr       <= '0;
      v_wrong_port       <= '0;
      v_lookup_refreshed <= '0;
      v_early_expiry     <= '0;
    end else begin
      // Capture the frame; the learn should follow within a few cycles.
      if (frame_valid) begin
        pend_q    <= 1'b1;
        pend_src  <= frame_src;
        pend_port <= frame_ingress;
        pend_elig <= frame_eligible;
      end
 
      if (pend_q && learn_valid) begin
        pend_q <= 1'b0;
        if (!pend_elig) begin
          // A frame that failed an eligibility rule produced a learn.
          if (!(&v_spurious_learn)) v_spurious_learn <= v_spurious_learn + 1'b1;
        end else begin
          if (learn_addr != pend_src)
            if (!(&v_wrong_addr)) v_wrong_addr <= v_wrong_addr + 1'b1;
          if (learn_port != pend_port)
            if (!(&v_wrong_port)) v_wrong_port <= v_wrong_port + 1'b1;
        end
      end else if (pend_q && frame_valid) begin
        // A second frame arrived before the first produced its learn.
        pend_q <= 1'b1;
        if (pend_elig)
          if (!(&v_missing_learn)) v_missing_learn <= v_missing_learn + 1'b1;
      end
 
      // THE SECTION 8 CHECK. An age field changed while a lookup was in
      // flight and no learn was in progress -- the design is refreshing
      // on destination activity, which keeps dead entries alive forever.
      if (age_written && lookup_valid && !learn_in_progress)
        if (!(&v_lookup_refreshed))
          v_lookup_refreshed <= v_lookup_refreshed + 1'b1;
 
      // An entry expired before reaching the configured interval, which
      // makes traffic to a live station flood for no reason.
      if (entry_expired && (expired_age < age_limit))
        if (!(&v_early_expiry)) v_early_expiry <= v_early_expiry + 1'b1;
    end
  end
 
  assign conformant = (v_missing_learn    == '0) &&
                      (v_spurious_learn   == '0) &&
                      (v_wrong_addr       == '0) &&
                      (v_wrong_port       == '0) &&
                      (v_lookup_refreshed == '0) &&
                      (v_early_expiry     == '0);
 
endmodule

// -----------------------------------------------------------------------
// port_down_flusher -- invalidates every entry naming a port whose link has
// dropped, and accelerates ageing after a port comes back.
//
// Two distinct responses to two distinct events:
//   link DOWN -- entries naming that port are CERTAINLY wrong. Flush them.
//   link UP   -- the topology may have changed underneath. Entries are
//               SUSPECT, not wrong. Accelerate ageing; do not flush.
// -----------------------------------------------------------------------
module port_down_flusher #(
  parameter int N_PORTS   = 24,
  parameter int PORT_BITS = 5,
  parameter int IDX_W     = 13,
  parameter int AGE_W     = 9,
  parameter int FAST_AGE  = 15,        // seconds, while topology is suspect
  parameter int SUSPECT_S = 30,        // how long to stay accelerated
  parameter int CNT_W     = 32
)(
  input  logic                 clk,
  input  logic                 rst_n,
  input  logic                 second_tick,
 
  input  logic [N_PORTS-1:0]   link_up,          // synchronised, debounced
 
  // Walk interface into the store: one entry per cycle.
  output logic                 walk_valid,
  output logic [IDX_W-1:0]     walk_index,
  input  logic                 walk_entry_valid,
  input  logic [PORT_BITS-1:0] walk_entry_port,
  output logic                 invalidate,
 
  output logic [AGE_W-1:0]     age_limit_out,    // to the store
  input  logic [AGE_W-1:0]     age_limit_normal, // 300 by default
 
  output logic [CNT_W-1:0]     c_flushed,
  output logic [CNT_W-1:0]     c_flush_events,
  output logic                 topology_suspect
);
 
  logic [N_PORTS-1:0] link_up_q;
  logic [N_PORTS-1:0] went_down, came_up;
 
  assign went_down = link_up_q & ~link_up;
  assign came_up   = ~link_up_q &  link_up;
 
  typedef enum logic [1:0] { F_IDLE, F_WALK, F_DONE } fst_e;
  fst_e                 st_q;
  logic [PORT_BITS-1:0] target_port;
  logic [IDX_W:0]       idx_q;
  logic [$clog2(512)-1:0] suspect_s_q;
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      link_up_q        <= '0;
      st_q             <= F_IDLE;
      idx_q            <= '0;
      target_port      <= '0;
      walk_valid       <= 1'b0;
      walk_index       <= '0;
      invalidate       <= 1'b0;
      c_flushed        <= '0;
      c_flush_events   <= '0;
      suspect_s_q      <= '0;
      topology_suspect <= 1'b0;
    end else begin
      link_up_q  <= link_up;
      walk_valid <= 1'b0;
      invalidate <= 1'b0;
 
      unique case (st_q)
        F_IDLE: begin
          // Priority-encode the lowest port that just dropped. A second
          // simultaneous drop is handled on the next pass -- the walk is
          // 8192 cycles at 500 MHz, which is 16.4 us, far shorter than
          // any plausible interval between two link events.
          for (int p = N_PORTS-1; p >= 0; p--)
            if (went_down[p]) begin
              target_port <= PORT_BITS'(p);
              st_q        <= F_WALK;
              idx_q       <= '0;
            end
          if (|went_down)
            if (!(&c_flush_events)) c_flush_events <= c_flush_events + 1'b1;
        end
 
        F_WALK: begin
          walk_valid <= 1'b1;
          walk_index <= idx_q[IDX_W-1:0];
          // The entry presented THIS cycle was requested last cycle.
          if (walk_entry_valid && (walk_entry_port == target_port)) begin
            invalidate <= 1'b1;
            if (!(&c_flushed)) c_flushed <= c_flushed + 1'b1;
          end
          if (idx_q[IDX_W-1:0] == {IDX_W{1'b1}}) st_q  <= F_DONE;
          else                                   idx_q <= idx_q + 1'b1;
        end
 
        F_DONE: st_q <= F_IDLE;
        default: st_q <= F_IDLE;
      endcase
 
      // A port COMING UP is a different event. Something was connected --
      // possibly a whole switch with stations behind it, possibly the same
      // cable back in the same socket. Entries are suspect, not wrong, so
      // accelerate ageing rather than destroying information that is
      // probably still correct.
      if (|came_up) suspect_s_q <= $clog2(512)'(SUSPECT_S);
      else if (second_tick && (suspect_s_q != '0))
        suspect_s_q <= suspect_s_q - 1'b1;
 
      topology_suspect <= (suspect_s_q != '0);
    end
  end
 
  assign age_limit_out = (suspect_s_q != '0) ? AGE_W'(FAST_AGE)
                                             : age_limit_normal;
 
endmodule

// P1. A group source address is NEVER learned. One bit test, and the
// omission with the worst symptom-to-cause distance in this chapter.
property p_group_source_never_learned;
  @(posedge clk) disable iff (!rst_n)
  (frame_valid && frame_src[40]) |-> !learn_valid;
endproperty
a_group_src: assert property (p_group_source_never_learned);
 
// P2. A frame that failed Chapter 7.3's check sequence is not evidence.
property p_bad_fcs_never_learned;
  @(posedge clk) disable iff (!rst_n)
  (frame_valid && frame_bad_fcs) |-> !learn_valid;
endproperty
a_bad_fcs: assert property (p_bad_fcs_never_learned);
 
// P3. A runt is not evidence -- its source field may be a fragment.
property p_runt_never_learned;
  @(posedge clk) disable iff (!rst_n)
  (frame_valid && frame_runt) |-> !learn_valid;
endproperty
a_runt: assert property (p_runt_never_learned);
 
// P4. The all-zero source is refused.
property p_null_source_refused;
  @(posedge clk) disable iff (!rst_n)
  (frame_valid && (frame_src == '0)) |-> !learn_valid;
endproperty
a_null_src: assert property (p_null_source_refused);
 
// P5. Refusals are CLASSIFIED, not merely counted -- each value has a
// different operational meaning.
property p_refusal_classified;
  @(posedge clk) disable iff (!rst_n)
  (frame_valid && !learn_valid) |-> (refusal != LE_OK);
endproperty
a_refusal_classified: assert property (p_refusal_classified);
 
// P6. An ELIGIBLE frame always produces a learn. Learning is not
// conditional on the frame's forwarding outcome.
property p_eligible_always_learns;
  @(posedge clk) disable iff (!rst_n)
  (frame_valid && frame_eligible) |-> learn_valid;
endproperty
a_eligible_learns: assert property (p_eligible_always_learns);

// P7. The learned port is the INGRESS port of the frame that produced it.
// Not the frame's destination port, not the previous entry's port.
property p_learn_port_is_ingress;
  @(posedge clk) disable iff (!rst_n)
  learn_valid |-> (learn_port == frame_ingress);
endproperty
a_learn_port: assert property (p_learn_port_is_ingress);
 
// P8. The learned address is the frame's SOURCE. The destination is
// never learned -- a switch has no evidence about where a destination is.
property p_learn_addr_is_source;
  @(posedge clk) disable iff (!rst_n)
  learn_valid |-> (learn_addr == frame_src);
endproperty
a_learn_addr: assert property (p_learn_addr_is_source);
 
// P9. One frame produces at most ONE learn.
property p_one_learn_per_frame;
  @(posedge clk) disable iff (!rst_n)
  learn_valid |=> !learn_valid until_with frame_valid;
endproperty
a_one_learn: assert property (p_one_learn_per_frame);
 
// P10. A known address on the SAME port is a refresh, never an insert --
// otherwise one station occupies many slots.
property p_same_port_is_refresh;
  @(posedge clk) disable iff (!rst_n)
  (learn_done && addr_known && (existing_port == learn_port))
    |-> (learn_result == LR_REFRESH);
endproperty
a_same_port_refresh: assert property (p_same_port_is_refresh);
 
// P11. A known address on a DIFFERENT port is a move, and the displaced
// port is reported -- the pair of ports IS the diagnosis.
property p_diff_port_is_move;
  @(posedge clk) disable iff (!rst_n)
  (learn_done && addr_known && (existing_port != learn_port))
    |-> ((learn_result == LR_MOVE) && (displaced_port == existing_port));
endproperty
a_diff_port_move: assert property (p_diff_port_is_move);

// P12. THE SECTION 8 PROPERTY. A lookup never touches an age field.
property p_lookup_does_not_refresh;
  @(posedge clk) disable iff (!rst_n)
  (lookup_valid && !learn_in_progress) |-> !age_written;
endproperty
a_lookup_no_refresh: assert property (p_lookup_does_not_refresh);
 
// P13. A refresh resets the age to zero, not to some smaller value.
property p_refresh_resets_age;
  @(posedge clk) disable iff (!rst_n)
  (learn_done && (learn_result == LR_REFRESH)) |=> (entry_age == '0);
endproperty
a_refresh_zeroes: assert property (p_refresh_resets_age);
 
// P14. An entry expires only at or after the configured interval.
property p_no_early_expiry;
  @(posedge clk) disable iff (!rst_n)
  entry_expired |-> (expired_age >= age_limit);
endproperty
a_no_early_expiry: assert property (p_no_early_expiry);
 
// P15. A statically configured entry NEVER ages. It was asserted, not
// inferred, so no timer may retract it.
property p_static_never_ages;
  @(posedge clk) disable iff (!rst_n)
  (entry_expired && entry_is_static) |-> 1'b0;
endproperty
a_static_persists: assert property (p_static_never_ages);
 
// P16. Expiry clears the entry's provenance -- a re-learn is a NEW claim
// and must not inherit a retracted claim's confidence.
property p_expiry_clears_evidence;
  @(posedge clk) disable iff (!rst_n)
  entry_expired |=> ((refreshes[$past(expired_index)] == '0) &&
                     (moves[$past(expired_index)]     == '0));
endproperty
a_expiry_clears: assert property (p_expiry_clears_evidence);

// P17. A full table REFUSES rather than evicting a live entry, so
// invented addresses cannot displace real stations.
property p_full_refuses_not_evicts;
  @(posedge clk) disable iff (!rst_n)
  (learn_valid && table_full && !addr_known) |-> (learn_result == LR_REJECT);
endproperty
a_full_refuses: assert property (p_full_refuses_not_evicts);
 
// P18. The rate limit applies to NEW addresses only. Refreshes and moves
// consume no capacity, so limiting them breaks real traffic and stops
// nothing.
property p_known_addresses_not_limited;
  @(posedge clk) disable iff (!rst_n)
  (learn_req && addr_is_known) |-> learn_permit;
endproperty
a_known_unlimited: assert property (p_known_addresses_not_limited);
 
// P19. The budget is PER PORT -- a shared budget lets one abusive port
// starve every other port's legitimate learning.
property p_budget_is_per_port;
  @(posedge clk) disable iff (!rst_n)
  (!learn_permit && learn_req && !addr_is_known)
    |-> (new_this_second[learn_port] >= CNT_W'(NEW_PER_SEC));
endproperty
a_per_port_budget: assert property (p_budget_is_per_port);
 
// P20. Occupancy never exceeds capacity.
property p_occupancy_bounded;
  @(posedge clk) disable iff (!rst_n)
  (occupancy <= (IDX_W+1)'(N_ENTRIES));
endproperty
a_occupancy_bounded: assert property (p_occupancy_bounded);
 
// P21. Every move records BOTH ports. One of them alone identifies
// nothing.
property p_move_records_both_ports;
  @(posedge clk) disable iff (!rst_n)
  (learn_done && (learn_result == LR_MOVE))
    |=> ((last_moved_from != last_moved_to));
endproperty
a_move_both_ports: assert property (p_move_records_both_ports);
 
// P22. A flap verdict names the address. "Something is flapping" is not
// actionable; a 48-bit value is.
property p_flap_names_address;
  @(posedge clk) disable iff (!rst_n)
  flapping |-> (flapping_addr != '0);
endproperty
a_flap_named: assert property (p_flap_names_address);

// P23. The monitor's verdict is the conjunction of its violation counts,
// and it means the RULE was applied -- never that the table is true.
property p_conformant_means_no_violations;
  @(posedge clk) disable iff (!rst_n)
  conformant |-> ((v_missing_learn == '0) && (v_spurious_learn == '0) &&
                  (v_wrong_addr == '0)    && (v_wrong_port == '0) &&
                  (v_lookup_refreshed == '0) && (v_early_expiry == '0));
endproperty
a_conformant_def: assert property (p_conformant_means_no_violations);
 
// P24. Every violation is attributed to a class. A single "error" bit
// would collapse six unrelated failures into one signal.
property p_violations_classified;
  @(posedge clk) disable iff (!rst_n)
  $rose(!conformant) |-> ($changed(v_missing_learn)    ||
                          $changed(v_spurious_learn)   ||
                          $changed(v_wrong_addr)       ||
                          $changed(v_wrong_port)       ||
                          $changed(v_lookup_refreshed) ||
                          $changed(v_early_expiry));
endproperty
a_violation_classified: assert property (p_violations_classified);
 
// P25. Confidence is advisory: the forwarding path must not consult it.
// A low-confidence entry is still the best answer available.
property p_confidence_does_not_gate_forwarding;
  @(posedge clk) disable iff (!rst_n)
  (lookup_valid && lookup_hit) |-> (lookup_port == entry_port);
endproperty
a_confidence_advisory: assert property (p_confidence_does_not_gate_forwarding);

// P26. A link going DOWN invalidates every entry naming that port. This
// is the one departure the switch is told about, and ignoring it wastes
// up to age_limit seconds of forwarding into a dead port.
property p_link_down_flushes_port;
  @(posedge clk) disable iff (!rst_n)
  (invalidate && walk_entry_valid) |-> (walk_entry_port == target_port);
endproperty
a_flush_targets_port: assert property (p_link_down_flushes_port);
 
// P27. A link going down NEVER invalidates an entry naming another port.
// A flush that over-reaches destroys correct information and floods the
// whole domain.
property p_flush_does_not_overreach;
  @(posedge clk) disable iff (!rst_n)
  (walk_valid && walk_entry_valid && (walk_entry_port != target_port))
    |-> !invalidate;
endproperty
a_flush_precise: assert property (p_flush_does_not_overreach);
 
// P28. A link coming UP accelerates ageing and does NOT flush. Entries
// are suspect, not wrong -- the cable may have gone back into the same
// socket.
property p_link_up_does_not_flush;
  @(posedge clk) disable iff (!rst_n)
  ($rose(|came_up)) |-> (!invalidate throughout topology_suspect[->1]);
endproperty
a_link_up_no_flush: assert property (p_link_up_does_not_flush);
 
// P29. While the topology is suspect, the store ages at the accelerated
// interval and not the normal one.
property p_accelerated_while_suspect;
  @(posedge clk) disable iff (!rst_n)
  topology_suspect |-> (age_limit_out == AGE_W'(FAST_AGE));
endproperty
a_fast_age_engaged: assert property (p_accelerated_while_suspect);
 
// P30. The accelerated interval EXPIRES. A switch that stays accelerated
// forever floods permanently, and nothing reports it.
property p_suspect_is_bounded;
  @(posedge clk) disable iff (!rst_n)
  $rose(topology_suspect) |-> ##[1:$] !topology_suspect;
endproperty
a_suspect_bounded: assert property (p_suspect_is_bounded);