LTSSM Overview — What the Link Is Currently Trying to Do

INPUTS                              OUTPUTS
receiver detection      ─┐      ┌─  PHY mode and power state
PHY lock / alignment    ─┤      ├─  training pattern generation
received ordered sets   ─┤ LTSSM├─  lane enable and configuration
timers                  ─┤      ├─  NORMAL TRAFFIC ENABLE
errors                  ─┤      ├─  recovery request
power-management req    ─┤      ├─  power-state control
reset / hot reset       ─┘      └─  link status, for software

// SYNTHESIZABLE. Normalized LTSSM state representation and observability.
//
// ============================================================
// THIS IS AN INTERNAL DEBUG ENUM, NOT A PCIe WIRE ENCODING.
//
// The values are this design's; PCIe does not define an encoding for
// LTSSM state on any interface. The STATE NAMES are the canonical major
// families (section 5); their entry/exit criteria belong to chapters
// 18.2-18.10 and appear nowhere in this module.
// ============================================================
package ltssm_pkg;
 
  typedef enum logic [3:0] {
    ST_DETECT        = 4'd0,
    ST_POLLING       = 4'd1,
    ST_CONFIGURATION = 4'd2,
    ST_L0            = 4'd3,
    ST_RECOVERY      = 4'd4,
    ST_L0S           = 4'd5,
    ST_L1            = 4'd6,
    ST_DISABLED      = 4'd7,
    ST_HOT_RESET     = 4'd8
  } ltssm_state_e;
 
  localparam int N_STATES = 9;
 
  // Why a transition happened, for the history register (section 11).
  // ILLUSTRATIVE categories -- not a PCIe enumeration.
  typedef enum logic [2:0] {
    RSN_NONE      = 3'd0,
    RSN_PROGRESS  = 3'd1,   // normal forward progress
    RSN_TIMEOUT   = 3'd2,
    RSN_ERROR     = 3'd3,
    RSN_PM        = 3'd4,   // power-management request
    RSN_RESET     = 3'd5,
    RSN_SOFTWARE  = 3'd6    // configuration-driven
  } ltssm_reason_e;
 
  function automatic bit state_legal(input logic [3:0] s);
    return (s < 4'(N_STATES));
  endfunction
 
  // NORMAL TLP/DLLP TRAFFIC IS LEGAL ONLY IN NORMAL OPERATION.
  // Scoped as this teaching model's contract: the exact set of states in
  // which traffic may flow is chapter 18.6's, and a design must take it
  // from there rather than from this one-line function.
  function automatic bit traffic_legal(input ltssm_state_e s);
    return (s == ST_L0);
  endfunction
 
endpackage

import ltssm_pkg::*;
 
// SYNTHESIZABLE. State observability: what the machine is doing, what it
// was doing, and how it got here.
// This is the register set an engineer reads FIRST when a Link fails
// (section 16). It observes; it never drives.
module ltssm_observe #(
  parameter int CNT_W = 16
) (
  input  logic clk,
  input  logic rst_n,
 
  // ---- From the state machine (which this module does NOT implement) ----
  input  ltssm_state_e  state,
  input  ltssm_reason_e reason,
 
  // ---- Debug-visible history ---------------------------------------------
  output ltssm_state_e  cur_state,
  output ltssm_state_e  prev_state,
  output ltssm_reason_e last_reason,
  output logic          state_changed,        // one cycle per transition
  output logic [CNT_W-1:0] transition_count,
  output logic [CNT_W-1:0] recovery_count,     // entries into Recovery
  output logic          illegal_state
);
 
  generate
    if (CNT_W < 1) $error("CNT_W must be at least 1");
  endgenerate
 
  ltssm_state_e  state_q, prev_q;
  ltssm_reason_e reason_q;
  logic [CNT_W-1:0] tcnt_q, rcnt_q;
  logic          ill_q;
 
  assign cur_state        = state_q;
  assign prev_state       = prev_q;
  assign last_reason      = reason_q;
  assign transition_count = tcnt_q;
  assign recovery_count   = rcnt_q;
  assign illegal_state    = ill_q;
 
  // THE TRANSITION EVENT. Compared against the REGISTERED state, so it is
  // exactly one cycle wide per change (P3) -- a comparison against a
  // combinational next-state would glitch.
  wire changed = (state != state_q);
  assign state_changed = changed;
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      state_q  <= ST_DETECT;
      prev_q   <= ST_DETECT;
      reason_q <= RSN_NONE;
      tcnt_q   <= '0; rcnt_q <= '0; ill_q <= 1'b0;
    end else begin
      state_q <= state;
 
      if (changed) begin
        // PREVIOUS STATE UPDATES ON THE TRANSITION, not before it. An
        // early update makes prev_state equal cur_state and destroys the
        // one piece of history that says where the machine came from
        // (section 18, mutation 2).
        prev_q   <= state_q;
        reason_q <= reason;
        // SATURATING. A wrapped count reads low and looks healthy, which
        // is the reading least distinguishable from a stable Link.
        if (tcnt_q != {CNT_W{1'b1}}) tcnt_q <= tcnt_q + CNT_W'(1);
 
        // RECOVERY ENTRIES ARE COUNTED SEPARATELY, because a Link that
        // keeps re-entering Recovery is the single most useful physical-
        // layer signal available to software (section 16).
        if ((state == ST_RECOVERY) && (rcnt_q != {CNT_W{1'b1}}))
          rcnt_q <= rcnt_q + CNT_W'(1);
      end
 
      if (!state_legal(state)) ill_q <= 1'b1;
    end
  end
 
endmodule

// SYNTHESIZABLE. A reusable dwell timer primitive.
// THE LTSSM USES TIMING CONDITIONS EXTENSIVELY, but NO PCIe TIMEOUT
// CONSTANT APPEARS HERE -- the normative values belong to the chapters
// that own each state (section 1). This is the mechanism only.
module ltssm_timer #(
  parameter int CNT_W = 24
) (
  input  logic clk,
  input  logic rst_n,
 
  input  logic             enable,
  input  logic             restart,          // e.g. a state change
  input  logic [CNT_W-1:0] limit,
 
  output logic [CNT_W-1:0] count,
  output logic             expired
);
 
  generate
    if (CNT_W < 1) $error("CNT_W must be at least 1");
  endgenerate
 
  logic [CNT_W-1:0] cnt_q;
  assign count = cnt_q;
 
  // ==================================================================
  // limit == 0 CONTRACT, DECLARED: the timer is DISABLED, never
  // instantly expired. A zero limit almost always means "not configured
  // yet", and treating it as immediate expiry fires every timeout in the
  // design during reset (section 18, mutation 6).
  // ==================================================================
  assign expired = enable && (limit != '0) && (cnt_q >= limit);
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      cnt_q <= '0;
    end else if (restart) begin
      // RESTART HAS PRIORITY OVER COUNTING, declared. A state change must
      // reset the dwell measurement even if the timer would have ticked
      // in the same cycle -- otherwise the new state inherits part of the
      // old state's elapsed time.
      cnt_q <= '0;
    end else if (enable && !expired) begin
      // SATURATING at the limit. A wrapping dwell timer would silently
      // re-arm and fire again, turning one timeout into a periodic one.
      cnt_q <= cnt_q + CNT_W'(1);
    end
  end
 
endmodule

import ltssm_pkg::*;
 
// SYNTHESIZABLE. One-cycle entry pulses, one per state.
// A small block with an outsized architectural effect (see below).
module ltssm_entry_pulse (
  input  logic         clk,
  input  logic         rst_n,
  input  ltssm_state_e state,
 
  output logic [N_STATES-1:0] enter,   // one-hot, one cycle per entry
  output logic                exit_any
);
 
  ltssm_state_e state_q;
  wire changed = (state != state_q);
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) state_q <= ST_DETECT;
    else        state_q <= state;
  end
 
  always_comb begin
    enter = '0;
    // EXACTLY ONE BIT, EXACTLY ONE CYCLE. One-hot by construction, because
    // it is indexed by the new state rather than assembled from
    // per-state comparisons that could disagree.
    if (changed && state_legal(state)) enter[state] = 1'b1;
  end
 
  assign exit_any = changed;
 
endmodule

import ltssm_pkg::*;
 
// SYNTHESIZABLE. Normal traffic is permitted only when the Link state
// says it is legal.
// THE GATING DISCIPLINE is Chapter 17.3 section 12's: gate BOTH
// directions, or a packet is destroyed at the boundary. Which states
// permit traffic is chapter 18.6's -- this model uses L0 only.
module ltssm_traffic_gate (
  input  ltssm_state_e state,
 
  input  logic up_valid,
  output logic up_ready,
  output logic down_valid,
  input  logic down_ready,
 
  output logic traffic_enabled
);
 
  assign traffic_enabled = traffic_legal(state);
 
  // ==================================================================
  // BOTH DIRECTIONS GATED.
  //
  // WRONG:  down_valid = up_valid && traffic_enabled;
  //         up_ready   = down_ready;              // <-- not gated
  //
  // With traffic_enabled = 0, up_valid = 1 and down_ready = 1, upstream
  // sees valid && ready and RELEASES the packet. Downstream sees
  // valid = 0 and receives nothing. The packet is destroyed -- and this
  // happens during Recovery and bring-up, when traffic is most likely to
  // be pushed and least likely to be instrumented (section 18).
  // ==================================================================
  assign down_valid = up_valid   && traffic_enabled;
  assign up_ready   = down_ready && traffic_enabled;
 
endmodule

import ltssm_pkg::*;
 
// SYNTHESIZABLE. Normalize control events from several engines into one
// prioritized stream for the state machine to consume.
// THE PRIORITY ORDER IS LOCAL IMPLEMENTATION POLICY, not a PCIe rule --
// the normative precedence among these conditions belongs to the
// chapters that own the states (section 1).
module ltssm_event_norm (
  input  logic clk,
  input  logic rst_n,
 
  // ---- From the physical and control engines -----------------------------
  input  logic detect_done,
  input  logic training_progress,
  input  logic config_done,
  input  logic recovery_needed,
  input  logic pm_request,
  input  logic hot_reset_seen,
  input  logic disable_request,
 
  // ---- Normalized, to the state machine -----------------------------------
  output logic          evt_valid,
  input  logic          evt_ready,
  output ltssm_reason_e evt_reason,
  output logic [2:0]    evt_source,
  output logic          evt_overflow
);
 
  // ==================================================================
  // PRIORITY, DECLARED AND ORDERED BY IRREVERSIBILITY.
  //
  // Reset-class events outrank power management, which outranks normal
  // progress -- because a reset invalidates the outcome of everything
  // below it, so deferring it would let the machine act on a decision
  // that is about to be discarded.
  //
  // This is THIS DESIGN'S ordering. PCIe's normative precedence among
  // these conditions is owned by chapters 18.2-18.10.
  // ==================================================================
  logic          v_q;
  ltssm_reason_e r_q;
  logic [2:0]    s_q;
  logic          ovf_q;
 
  assign evt_valid    = v_q;
  assign evt_reason   = r_q;
  assign evt_source   = s_q;
  assign evt_overflow = ovf_q;
 
  logic          sel_any;
  ltssm_reason_e sel_reason;
  logic [2:0]    sel_source;
 
  always_comb begin
    sel_any = 1'b1;
    if      (hot_reset_seen)    begin sel_reason = RSN_RESET;    sel_source = 3'd0; end
    else if (disable_request)   begin sel_reason = RSN_SOFTWARE; sel_source = 3'd1; end
    else if (recovery_needed)   begin sel_reason = RSN_ERROR;    sel_source = 3'd2; end
    else if (pm_request)        begin sel_reason = RSN_PM;       sel_source = 3'd3; end
    else if (config_done)       begin sel_reason = RSN_PROGRESS; sel_source = 3'd4; end
    else if (detect_done)       begin sel_reason = RSN_PROGRESS; sel_source = 3'd5; end
    else if (training_progress) begin sel_reason = RSN_PROGRESS; sel_source = 3'd6; end
    else begin sel_any = 1'b0; sel_reason = RSN_NONE; sel_source = 3'd7; end
  end
 
  wire fire     = v_q && evt_ready;
  wire can_take = !v_q || evt_ready;
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      v_q <= 1'b0; r_q <= RSN_NONE; s_q <= 3'd7; ovf_q <= 1'b0;
    end else begin
      // Capture beats drain, so a same-cycle accept-and-consume holds the
      // new event rather than dropping it.
      if (sel_any && can_take) begin
        v_q <= 1'b1; r_q <= sel_reason; s_q <= sel_source;
      end else if (fire) begin
        v_q <= 1'b0;
      end
 
      // An event that could not be held is REPORTED. A lost reset or
      // recovery request is not something to discover in the lab.
      if (sel_any && !can_take) ovf_q <= 1'b1;
    end
  end
 
endmodule

         top-level major-mode controller
                      │
     ┌────────┬───────┼────────┬──────────┐
   Detect  Polling  Config  Recovery   Power
   subctl   subctl  subctl   subctl    subctl

child_start    →    "begin your work"
child_active   ←    "I am working"
child_done     ←    "I finished successfully"
child_fail     ←    "I could not"
child_result   ←    whatever the parent needs (width, lane map, rate)

import ltssm_pkg::*;
 
// SYNTHESIZABLE. Lab-visibility monitor: warn when the machine has not
// moved for an unusually long time.
//
// ============================================================
// THIS IS DIAGNOSTIC ONLY. IT NEVER DRIVES A STATE TRANSITION.
//
// A monitor that could force the machine would be a second, undeclared
// controller -- and the resulting behaviour would depend on a debug
// threshold rather than on protocol conditions. The real timeouts belong
// to the chapters that own each state (section 1); this warns, and that
// is all it does.
// ============================================================
module ltssm_stuck_monitor #(
  parameter int CNT_W = 24
) (
  input  logic             clk,
  input  logic             rst_n,
  input  ltssm_state_e     state,
  input  logic             state_changed,
  input  logic [CNT_W-1:0] warn_limit,      // debug threshold, software-set
 
  output logic             stuck_warning,
  output ltssm_state_e     stuck_state,
  output logic [CNT_W-1:0] dwell
);
 
  logic [CNT_W-1:0] dwell_q;
  logic             warn_q;
  ltssm_state_e     stuck_q;
 
  assign dwell         = dwell_q;
  assign stuck_warning = warn_q;
  assign stuck_state   = stuck_q;
 
  wire at_limit = (warn_limit != '0) && (dwell_q >= warn_limit);
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      dwell_q <= '0; warn_q <= 1'b0; stuck_q <= ST_DETECT;
    end else if (state_changed) begin
      // A transition clears the dwell measurement. The WARNING is sticky
      // so a transient stall that has since resolved is still readable --
      // which is the whole reason a debug register exists.
      dwell_q <= '0;
    end else begin
      if (dwell_q != {CNT_W{1'b1}}) dwell_q <= dwell_q + CNT_W'(1);
      if (at_limit && !warn_q) begin
        warn_q  <= 1'b1;
        stuck_q <= state;             // WHICH state it was stuck in
      end
    end
  end
 
endmodule

step             1      2      3      4      5      6      7      8
state           DET    POL    CFG    L0     L0    RECOV  RECOV   L0
state_changed    -      1      1      1      0      1      0      1
prev_state      DET    DET    POL    CFG    CFG    L0     L0    RECOV
last_reason      -    PROG   PROG   PROG   PROG   ERROR  ERROR  PROG
transition_cnt   0      1      2      3      3      4      4      5
recovery_cnt     0      0      0      0      0      1      1      1
 
traffic_enabled  0      0      0      1      1      0      0      1
up_valid         1      1      1      1      1      1      1      1
up_ready         0      0      0      1      1      0      0      1
down_valid       0      0      0      1      1      0      0      1

// SVA over ltssm_observe, ltssm_timer, ltssm_entry_pulse,
// ltssm_traffic_gate, ltssm_event_norm and ltssm_stuck_monitor.
//
// These assert the OVERVIEW INFRASTRUCTURE's contract. They assert
// NOTHING about PCIe's legal state transitions, entry or exit criteria,
// or timeout values -- all owned by chapters 18.2-18.10 (section 1) --
// and nothing about training eventually succeeding, which depends on a
// partner and a channel this design does not control.
 
// ---- ENVIRONMENT ------------------------------------------------------
// A1: the state input is a legal encoding.
assume property (@(posedge clk) disable iff (!rst_n) state_legal(state));
// A2: reason accompanies a transition.
assume property (@(posedge clk) disable iff (!rst_n)
  (state != $past(state)) |-> (reason != RSN_NONE));
 
// ---- STATE OBSERVABILITY ----------------------------------------------
 
// P1: the exposed state tracks the machine with a defined one-cycle
// relationship -- never an ambiguous mixture.
property p_state_tracks;
  @(posedge clk) disable iff (!rst_n)
  cur_state == $past(state);
endproperty
a_track : assert property (p_state_tracks);
 
// P2: PREVIOUS STATE IS THE STATE BEFORE THE TRANSITION. Updating it
// early makes it equal cur_state and destroys the history.
property p_prev_correct;
  @(posedge clk) disable iff (!rst_n)
  $rose(state_changed) |=> (prev_state == $past(cur_state, 2));
endproperty
a_prev : assert property (p_prev_correct);
 
// P3: the transition count increments EXACTLY ONCE per change.
property p_count_once;
  @(posedge clk) disable iff (!rst_n)
  (transition_count != $past(transition_count))
    |-> ($past(state_changed)
      && (transition_count == $past(transition_count) + 1));
endproperty
a_count : assert property (p_count_once);
 
// P3b: and it does not move while the state is stable.
property p_count_stable;
  @(posedge clk) disable iff (!rst_n)
  !state_changed |=> $stable(transition_count);
endproperty
a_count_stable : assert property (p_count_stable);
 
// P3c: recovery_count increments on ENTRY to Recovery, not per cycle in it.
property p_recovery_on_entry;
  @(posedge clk) disable iff (!rst_n)
  (recovery_count != $past(recovery_count))
    |-> ($past(state_changed) && ($past(state) == ST_RECOVERY));
endproperty
a_rec : assert property (p_recovery_on_entry);
 
// ---- ENTRY PULSES -----------------------------------------------------
 
// P4: EXACTLY ONE entry pulse per transition, and it is one-hot.
property p_entry_one_hot;
  @(posedge clk) disable iff (!rst_n)
  (state != $past(state)) |-> ($countones(enter) == 1);
endproperty
a_entry : assert property (p_entry_one_hot);
 
// P5: NO entry pulse while the state is stable. The complementary half --
// a design producing a level rather than a pulse fails here.
property p_no_pulse_when_stable;
  @(posedge clk) disable iff (!rst_n)
  (state == $past(state)) |-> (enter == '0);
endproperty
a_stable : assert property (p_no_pulse_when_stable);
 
// P6: the pulse names the state being ENTERED.
property p_entry_names_new_state;
  @(posedge clk) disable iff (!rst_n)
  (enter != '0) |-> enter[state];
endproperty
a_names : assert property (p_entry_names_new_state);
 
// ---- TIMER ------------------------------------------------------------
 
// P7: the timer RESTARTS on a state change -- a new state never inherits
// the previous state's elapsed time.
property p_timer_restarts;
  @(posedge clk) disable iff (!rst_n)
  restart |=> (count == '0);
endproperty
a_restart : assert property (p_timer_restarts);
 
// P7b: limit == 0 means DISABLED, never instantly expired.
property p_zero_limit_disables;
  @(posedge clk) disable iff (!rst_n)
  (limit == '0) |-> !expired;
endproperty
a_zero : assert property (p_zero_limit_disables);
 
// P7c: SATURATES rather than wrapping -- the count never decreases
// except on a restart.
property p_timer_saturates;
  @(posedge clk) disable iff (!rst_n)
  (count < $past(count)) |-> $past(restart);
endproperty
a_sat : assert property (p_timer_saturates);
 
// ---- TRAFFIC GATE -----------------------------------------------------
 
// P8: THE CHAPTER'S CENTRAL PROPERTY. A packet blocked by an illegal
// state remains UPSTREAM-OWNED -- neither transferred nor destroyed.
// This is the property section 18's counterexample fails.
property p_packet_stays_upstream;
  @(posedge clk) disable iff (!rst_n)
  (up_valid && !traffic_enabled) |-> (!up_ready && !down_valid);
endproperty
a_ownership : assert property (p_packet_stays_upstream);
 
// P9: no transfer occurs while traffic is not legal.
property p_no_transfer_when_illegal;
  @(posedge clk) disable iff (!rst_n)
  !traffic_enabled |-> !(up_valid && up_ready);
endproperty
a_gated : assert property (p_no_transfer_when_illegal);
 
// P10: traffic_enabled implies the teaching model's traffic state.
property p_enabled_implies_l0;
  @(posedge clk) disable iff (!rst_n)
  traffic_enabled |-> (cur_state == ST_L0);
endproperty
a_l0 : assert property (p_enabled_implies_l0);
 
// P11: when traffic IS legal the gate is transparent -- it adds no
// behaviour of its own.
property p_transparent;
  @(posedge clk) disable iff (!rst_n)
  traffic_enabled |-> ((down_valid == up_valid) && (up_ready == down_ready));
endproperty
a_transparent : assert property (p_transparent);
 
// ---- EVENTS -----------------------------------------------------------
 
// P12: an event that could not be held is REPORTED, never silent.
property p_event_overflow_reported;
  @(posedge clk) disable iff (!rst_n)
  (sel_any && !can_take) |=> evt_overflow;
endproperty
a_ovf : assert property (p_event_overflow_reported);
 
// P13: the declared priority holds -- a reset-class event outranks
// everything beneath it.
property p_reset_priority;
  @(posedge clk) disable iff (!rst_n)
  (hot_reset_seen && can_take) |=> (evt_reason == RSN_RESET);
endproperty
a_priority : assert property (p_reset_priority);
 
// ---- SCOPE ------------------------------------------------------------
 
// P14: THE DIAGNOSTIC MONITOR NEVER DRIVES THE STATE MACHINE. A monitor
// that could force a transition would be a second, undeclared controller
// whose behaviour depended on a debug threshold (section 15).
property p_monitor_does_not_drive;
  @(posedge clk) disable iff (!rst_n)
  $rose(stuck_warning) |=> $stable(cur_state);
endproperty
a_scope : assert property (p_monitor_does_not_drive);
 
// P15: the stuck monitor captures WHICH state it was stuck in.
property p_stuck_state_captured;
  @(posedge clk) disable iff (!rst_n)
  $rose(stuck_warning) |-> (stuck_state == cur_state);
endproperty
a_stuck : assert property (p_stuck_state_captured);
 
// P16: reset initializes the observability set to a defined value.
property p_reset;
  @(posedge clk)
  !rst_n |=> ((transition_count == '0) && (recovery_count == '0)
           && !stuck_warning && !traffic_enabled);
endproperty
a_reset : assert property (p_reset);