USB 3.x Packets

  [ HEADER : 14 bytes ][ CRC-16 ][  PAYLOAD  ][ CRC-32 ]
   \_______ one CRC domain ______/  \__ a second CRC domain __/
        type, route, sequence          only a Data Packet
        number, subtype, flags         has this part at all

// WRONG -- decode first, validate afterwards
always_comb begin
  case (hdr_type)                 // reads the type field unconditionally
    T_LMP: pkt_type = PKT_LMP;
    T_TP:  pkt_type = PKT_TP;
    ...
  endcase
  if (!hdr_crc_ok) flag_an_error(); // ... and *then* notices it was garbage
end

// RIGHT -- the CRC gates the decode
always_comb begin
  if (!pkt_valid)       pkt_type = PKT_NONE;
  else if (!hdr_crc_ok) pkt_type = PKT_UNKNOWN;   // stop here. Read nothing.
  else case (hdr_type)
    ...
  endcase
end

  usb3_packet_decode

  inputs                          outputs
  ------                          -------
  pkt_valid                       pkt_type         (7 outcomes)
  hdr_type        [4:0]           route            (4 outcomes)
  hdr_crc_ok                      hdr_error
  payload_present                 payload_error
  payload_crc_ok                  link_retry_req
                                  protocol_nak_req
                                  ack_expected

                                  hdr_errors       [31:0]
                                  payload_errors   [31:0]
                                  reserved_types   [31:0]
                                  delivered        [31:0]

  2 (pkt_valid)   x  32 (hdr_type)  x  2 (hdr_crc_ok)
                  x   2 (payload_present)  x  2 (payload_crc_ok)

                  =  512 points, ALL of them reachable

// usb3_packet_decode -- four packet types, two independent CRCs, and why a
// corrupt header is a different kind of problem from corrupt data.
//
// A SuperSpeed packet begins with a 14-byte HEADER carrying its type and its
// routing, followed by a 2-byte CRC over that header alone. A Data Packet
// then carries a PAYLOAD with its own, separate CRC.
//
//     [ header : 14 bytes ][ header CRC-16 ][ payload ][ payload CRC-32 ]
//      \______ protected together ______/    \___ protected separately __/
//
// THE STRUCTURAL DECISION
//
// Those two CRCs are not redundancy. They protect two things that fail in
// different ways and are recovered by different layers:
//
//   HEADER CRC BAD    The type and routing are UNKNOWN. The link layer
//                     cannot even tell what kind of packet this was, let
//                     alone which endpoint it belonged to. Nothing above
//                     the link layer can be told about it, because there is
//                     nothing to tell them. Recovery is a LINK-level retry.
//
//   PAYLOAD CRC BAD   The header was good, so the type, the endpoint and
//                     the sequence number are all known and trustworthy.
//                     Exactly one endpoint's data is bad, and the protocol
//                     layer can ask for that one packet again.
//
// THE CONSEQUENCE, AND IT IS THE POINT OF THE MODULE
//
// When the header CRC fails, the type field MUST NOT BE DECODED. The bits
// are there and they will parse into something -- but they are bits a CRC
// has just declared untrustworthy, and acting on them routes a packet
// somewhere on the strength of data known to be corrupt.
//
// A design that decodes the type first and checks the CRC afterwards works
// perfectly until the first corrupted header, and then delivers garbage to
// whichever endpoint the damaged bits happened to name.
//
// RESERVED TYPES ARE NOT A FIFTH KIND
//
// The 5-bit type field has 32 encodings and four are defined. The other 28
// are reserved, and a packet carrying one has a VALID CRC and an
// UNINTERPRETABLE type -- which is a third case, distinct from both a CRC
// failure and a known type, and it is discarded without a link retry
// because retrying will produce the same reserved value again.
module usb3_packet_decode (
  input  wire        clk,
  input  wire        rst_n,

  input  wire        pkt_valid,
  input  wire [4:0]  hdr_type,        // the header's Type field
  input  wire        hdr_crc_ok,      // the 16-bit header CRC checked out
  input  wire        payload_present, // a Data Packet carries one
  input  wire        payload_crc_ok,  // the 32-bit payload CRC checked out

  output wire [2:0]  pkt_type,
  output wire [1:0]  route,
  output wire        hdr_error,
  output wire        payload_error,
  output wire        link_retry_req,  // LINK layer: resend the whole packet
  output wire        protocol_nak_req,// PROTOCOL layer: resend this data
  output wire        ack_expected,    // ITP is never acknowledged

  output reg  [31:0] hdr_errors,
  output reg  [31:0] payload_errors,
  output reg  [31:0] reserved_types,
  output reg  [31:0] delivered
);
  // The four defined Type encodings. Everything else is reserved.
  localparam [4:0] T_LMP = 5'h00,   // Link Management -- stays at the link
                   T_TP  = 5'h04,   // Transaction Packet
                   T_DP  = 5'h08,   // Data Packet -- the only one with a payload
                   T_ITP = 5'h0C;   // Isochronous Timestamp -- broadcast

  localparam [2:0] P_NONE = 3'd0,   // no packet this cycle
                   P_LMP  = 3'd1,
                   P_TP   = 3'd2,
                   P_DP   = 3'd3,
                   P_ITP  = 3'd4,
                   P_RSVD = 3'd5,   // valid CRC, undefined type
                   P_UNKNOWN = 3'd6;// the CRC failed: the type is NOT known

  localparam [1:0] R_NONE     = 2'd0,
                   R_LINK     = 2'd1,   // the link layer consumes it
                   R_PROTOCOL = 2'd2,   // it goes up to the endpoint
                   R_DISCARD  = 2'd3;

  // THE DECODE, AND ITS ORDER. The CRC is consulted BEFORE the type field,
  // not after. With a bad header CRC the type is reported as P_UNKNOWN --
  // not as whatever the corrupt bits happen to spell.
  assign pkt_type = !pkt_valid   ? P_NONE
                  : !hdr_crc_ok  ? P_UNKNOWN
                  : (hdr_type == T_LMP) ? P_LMP
                  : (hdr_type == T_TP)  ? P_TP
                  : (hdr_type == T_DP)  ? P_DP
                  : (hdr_type == T_ITP) ? P_ITP
                                        : P_RSVD;

  // A Data Packet whose payload failed its own CRC still has a GOOD header,
  // so it is still routed: the protocol layer needs to know which endpoint
  // to ask again, and that information is in the header it can trust.
  assign route = (pkt_type == P_NONE)    ? R_NONE
               : (pkt_type == P_UNKNOWN) ? R_DISCARD
               : (pkt_type == P_RSVD)    ? R_DISCARD
               : (pkt_type == P_LMP)     ? R_LINK
                                         : R_PROTOCOL;

  assign hdr_error     = pkt_valid && !hdr_crc_ok;
  // A payload error is only meaningful on a Data Packet with a good header.
  // Reporting one after a header failure would be claiming to know that the
  // payload was bad -- which requires knowing there WAS a payload, which
  // requires the header.
  assign payload_error = pkt_valid && hdr_crc_ok
                      && (pkt_type == P_DP) && payload_present
                      && !payload_crc_ok;

  // TWO DIFFERENT RECOVERIES, and they are mutually exclusive by
  // construction: one of them needs a header the other one does not have.
  assign link_retry_req   = hdr_error;
  assign protocol_nak_req = payload_error;

  // An Isochronous Timestamp Packet is broadcast and never acknowledged --
  // an ACK would be pointless for a timestamp, which is stale the moment it
  // is questioned. LMPs are link-level and acknowledged differently.
  assign ack_expected = (pkt_type == P_TP) || (pkt_type == P_DP);

  always @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      hdr_errors     <= 32'd0;
      payload_errors <= 32'd0;
      reserved_types <= 32'd0;
      delivered      <= 32'd0;
    end else if (pkt_valid) begin
      if (hdr_error)              hdr_errors     <= hdr_errors + 32'd1;
      if (payload_error)          payload_errors <= payload_errors + 32'd1;
      if (pkt_type == P_RSVD)     reserved_types <= reserved_types + 32'd1;
      if (route != R_DISCARD && route != R_NONE)
                                  delivered      <= delivered + 32'd1;
    end
  end
endmodule

// usb3_packet_decode -- four packet types, two independent CRCs, and why a
// corrupt header is a different kind of problem from corrupt data.
//
// A SuperSpeed packet begins with a 14-byte HEADER carrying its type and its
// routing, followed by a 2-byte CRC over that header alone. A Data Packet
// then carries a PAYLOAD with its own, separate CRC.
//
//     [ header : 14 bytes ][ header CRC-16 ][ payload ][ payload CRC-32 ]
//      \______ protected together ______/    \___ protected separately __/
//
// The SystemVerilog build names the two classifications with enums, which is
// what makes the central rule visible in the waveform viewer: when the header
// CRC fails the type reads PKT_UNKNOWN, not "the type the corrupt bits spell".
package usb3_packet_pkg;
  // The four defined Type encodings. Everything else is reserved.
  typedef enum logic [4:0] {
    T_LMP = 5'h00,   // Link Management -- stays at the link layer
    T_TP  = 5'h04,   // Transaction Packet
    T_DP  = 5'h08,   // Data Packet -- the only one with a payload
    T_ITP = 5'h0C    // Isochronous Timestamp -- broadcast, never acknowledged
  } hdr_type_e;

  typedef enum logic [2:0] {
    PKT_NONE    = 3'd0,  // no packet this cycle
    PKT_LMP     = 3'd1,
    PKT_TP      = 3'd2,
    PKT_DP      = 3'd3,
    PKT_ITP     = 3'd4,
    PKT_RSVD    = 3'd5,  // valid CRC, undefined type encoding
    PKT_UNKNOWN = 3'd6   // the header CRC FAILED: the type is not known
  } pkt_type_e;

  typedef enum logic [1:0] {
    ROUTE_NONE     = 2'd0,
    ROUTE_LINK     = 2'd1,  // the link layer consumes it
    ROUTE_PROTOCOL = 2'd2,  // it goes up to the endpoint
    ROUTE_DISCARD  = 2'd3
  } route_e;
endpackage

// THE STRUCTURAL DECISION
//
// The two CRCs are not redundancy. They protect two things that fail in
// different ways and are recovered by different layers:
//
//   HEADER CRC BAD    The type and routing are UNKNOWN. The link layer cannot
//                     tell what kind of packet this was, let alone which
//                     endpoint it belonged to. Nothing above the link layer
//                     can be told about it, because there is nothing to tell
//                     them. Recovery is a LINK-level retry.
//
//   PAYLOAD CRC BAD   The header was good, so the type, the endpoint and the
//                     sequence number are all known and trustworthy. Exactly
//                     one endpoint's data is bad and the protocol layer can
//                     ask for that one packet again.
//
// THE CONSEQUENCE, AND IT IS THE POINT OF THE MODULE
//
// When the header CRC fails, the type field MUST NOT BE DECODED. The bits are
// there and they will parse into something -- but they are bits a CRC has
// just declared untrustworthy, and acting on them routes a packet somewhere
// on the strength of data known to be corrupt.
//
// RESERVED TYPES ARE NOT A FIFTH KIND
//
// The 5-bit type field has 32 encodings and four are defined. The other 28 are
// reserved, and a packet carrying one has a VALID CRC and an UNINTERPRETABLE
// type -- a third case, distinct from both a CRC failure and a known type. It
// is discarded WITHOUT a link retry, because retrying will produce the same
// reserved value again.
module usb3_packet_decode
  import usb3_packet_pkg::*;
(
  input  logic        clk,
  input  logic        rst_n,

  input  logic        pkt_valid,
  input  logic [4:0]  hdr_type,        // the header's Type field
  input  logic        hdr_crc_ok,      // the 16-bit header CRC checked out
  input  logic        payload_present, // a Data Packet carries one
  input  logic        payload_crc_ok,  // the 32-bit payload CRC checked out

  output pkt_type_e   pkt_type,
  output route_e      route,
  output logic        hdr_error,
  output logic        payload_error,
  output logic        link_retry_req,  // LINK layer: resend the whole packet
  output logic        protocol_nak_req,// PROTOCOL layer: resend this data
  output logic        ack_expected,    // ITP is never acknowledged

  output logic [31:0] hdr_errors,
  output logic [31:0] payload_errors,
  output logic [31:0] reserved_types,
  output logic [31:0] delivered
);
  pkt_type_e pkt_type_c;
  route_e    route_c;

  // THE DECODE, AND ITS ORDER. The CRC is consulted BEFORE the type field,
  // never after. With a bad header CRC the type is PKT_UNKNOWN.
  always_comb begin
    if (!pkt_valid)      pkt_type_c = PKT_NONE;
    else if (!hdr_crc_ok) pkt_type_c = PKT_UNKNOWN;
    else begin
      case (hdr_type)
        T_LMP:   pkt_type_c = PKT_LMP;
        T_TP:    pkt_type_c = PKT_TP;
        T_DP:    pkt_type_c = PKT_DP;
        T_ITP:   pkt_type_c = PKT_ITP;
        default: pkt_type_c = PKT_RSVD;
      endcase
    end
  end

  // A Data Packet whose payload failed its own CRC still has a GOOD header,
  // so it is still routed: the protocol layer needs to know which endpoint to
  // ask again, and that information is in the header it can trust.
  always_comb begin
    case (pkt_type_c)
      PKT_NONE:               route_c = ROUTE_NONE;
      PKT_UNKNOWN, PKT_RSVD:  route_c = ROUTE_DISCARD;
      PKT_LMP:                route_c = ROUTE_LINK;
      default:                route_c = ROUTE_PROTOCOL;
    endcase
  end

  assign pkt_type = pkt_type_c;
  assign route    = route_c;

  assign hdr_error = pkt_valid && !hdr_crc_ok;
  // A payload error is only meaningful on a Data Packet with a good header.
  // Reporting one after a header failure would be claiming to know that the
  // payload was bad -- which requires knowing there WAS a payload, which
  // requires the header.
  assign payload_error = pkt_valid && hdr_crc_ok
                      && (pkt_type_c == PKT_DP) && payload_present
                      && !payload_crc_ok;

  // TWO DIFFERENT RECOVERIES, mutually exclusive by construction: one of them
  // needs a header the other one does not have.
  assign link_retry_req   = hdr_error;
  assign protocol_nak_req = payload_error;

  // An ITP is broadcast and never acknowledged -- an ACK for a timestamp is
  // pointless, since it is stale the moment it is questioned. LMPs are
  // link-level and acknowledged differently.
  assign ack_expected = (pkt_type_c == PKT_TP) || (pkt_type_c == PKT_DP);

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      hdr_errors     <= '0;
      payload_errors <= '0;
      reserved_types <= '0;
      delivered      <= '0;
    end else if (pkt_valid) begin
      if (hdr_error)              hdr_errors     <= hdr_errors + 1;
      if (payload_error)          payload_errors <= payload_errors + 1;
      if (pkt_type_c == PKT_RSVD) reserved_types <= reserved_types + 1;
      if (route_c != ROUTE_DISCARD && route_c != ROUTE_NONE)
                                  delivered      <= delivered + 1;
    end
  end
endmodule

-- usb3_packet_decode -- four packet types, two independent CRCs, and why a
-- corrupt header is a different kind of problem from corrupt data.
--
-- A SuperSpeed packet begins with a 14-byte HEADER carrying its type and its
-- routing, followed by a 2-byte CRC over that header alone. A Data Packet
-- then carries a PAYLOAD with its own, separate CRC.
--
--     [ header : 14 bytes ][ header CRC-16 ][ payload ][ payload CRC-32 ]
--      \______ protected together ______/    \___ protected separately __/
--
-- VHDL's strong enumeration types make the central rule structural rather
-- than conventional: PKT_UNKNOWN is a distinct value of pkt_type_t, so a
-- downstream case statement that forgets to handle "the header was corrupt"
-- fails to elaborate rather than falling through to a default.
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

package usb3_packet_pkg is
  -- Seven outcomes, and the last two are the interesting ones: PKT_RSVD is a
  -- GOOD header carrying an undefined encoding, PKT_UNKNOWN is a header whose
  -- CRC failed so no encoding can be read from it at all.
  type pkt_type_t is (PKT_NONE, PKT_LMP, PKT_TP, PKT_DP, PKT_ITP,
                      PKT_RSVD, PKT_UNKNOWN);
  type route_t    is (ROUTE_NONE, ROUTE_LINK, ROUTE_PROTOCOL, ROUTE_DISCARD);

  function pkt_code  (p : pkt_type_t) return std_logic_vector;
  function route_code(r : route_t)    return std_logic_vector;
end package;

package body usb3_packet_pkg is
  function pkt_code (p : pkt_type_t) return std_logic_vector is
  begin
    return std_logic_vector(to_unsigned(pkt_type_t'pos(p), 3));
  end function;
  function route_code (r : route_t) return std_logic_vector is
  begin
    return std_logic_vector(to_unsigned(route_t'pos(r), 2));
  end function;
end package body;

library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;
use work.usb3_packet_pkg.all;

-- THE STRUCTURAL DECISION
--
-- The two CRCs are not redundancy. They protect two things that fail in
-- different ways and are recovered by different layers:
--
--   HEADER CRC BAD    The type and routing are UNKNOWN. The link layer cannot
--                     tell what kind of packet this was, let alone which
--                     endpoint it belonged to. Recovery is a LINK-level retry.
--
--   PAYLOAD CRC BAD   The header was good, so the type, the endpoint and the
--                     sequence number are all trustworthy. Exactly one
--                     endpoint's data is bad and the protocol layer can ask
--                     for that one packet again.
--
-- THE CONSEQUENCE: when the header CRC fails, the type field MUST NOT BE
-- DECODED. The bits are there and they will parse into something -- but they
-- are bits a CRC has just declared untrustworthy.
--
-- RESERVED TYPES ARE NOT A FIFTH KIND. Four of the 32 encodings are defined;
-- a packet carrying one of the other 28 has a VALID CRC and an
-- UNINTERPRETABLE type, and is discarded WITHOUT a link retry, because
-- retrying will produce the same reserved value again.
entity usb3_packet_decode is
  port (
    clk              : in  std_logic;
    rst_n            : in  std_logic;

    pkt_valid        : in  std_logic;
    hdr_type         : in  std_logic_vector(4 downto 0);
    hdr_crc_ok       : in  std_logic;
    payload_present  : in  std_logic;
    payload_crc_ok   : in  std_logic;

    pkt_type         : out std_logic_vector(2 downto 0);
    route            : out std_logic_vector(1 downto 0);
    hdr_error        : out std_logic;
    payload_error    : out std_logic;
    link_retry_req   : out std_logic;
    protocol_nak_req : out std_logic;
    ack_expected     : out std_logic;

    hdr_errors       : out std_logic_vector(31 downto 0);
    payload_errors   : out std_logic_vector(31 downto 0);
    reserved_types   : out std_logic_vector(31 downto 0);
    delivered        : out std_logic_vector(31 downto 0)
  );
end entity;

architecture rtl of usb3_packet_decode is
  -- The four defined Type encodings. Everything else is reserved.
  constant T_LMP : std_logic_vector(4 downto 0) := "00000";  -- 0x00
  constant T_TP  : std_logic_vector(4 downto 0) := "00100";  -- 0x04
  constant T_DP  : std_logic_vector(4 downto 0) := "01000";  -- 0x08
  constant T_ITP : std_logic_vector(4 downto 0) := "01100";  -- 0x0C

  signal ptype  : pkt_type_t;
  signal rt     : route_t;
  signal he     : std_logic;
  signal pe     : std_logic;

  signal he_r, pe_r, rs_r, dl_r : unsigned(31 downto 0) := (others => '0');
begin
  -- THE DECODE, AND ITS ORDER. The CRC is consulted BEFORE the type field,
  -- never after. With a bad header CRC the type is PKT_UNKNOWN.
  decode : process (pkt_valid, hdr_crc_ok, hdr_type)
  begin
    if pkt_valid = '0' then
      ptype <= PKT_NONE;
    elsif hdr_crc_ok = '0' then
      ptype <= PKT_UNKNOWN;
    else
      case hdr_type is
        when T_LMP  => ptype <= PKT_LMP;
        when T_TP   => ptype <= PKT_TP;
        when T_DP   => ptype <= PKT_DP;
        when T_ITP  => ptype <= PKT_ITP;
        when others => ptype <= PKT_RSVD;
      end case;
    end if;
  end process;

  -- A Data Packet whose payload failed its own CRC still has a GOOD header,
  -- so it is still routed: the protocol layer needs to know which endpoint to
  -- ask again, and that is in the header it can trust.
  routing : process (ptype)
  begin
    case ptype is
      when PKT_NONE                => rt <= ROUTE_NONE;
      when PKT_UNKNOWN | PKT_RSVD  => rt <= ROUTE_DISCARD;
      when PKT_LMP                 => rt <= ROUTE_LINK;
      when others                  => rt <= ROUTE_PROTOCOL;
    end case;
  end process;

  he <= '1' when (pkt_valid = '1' and hdr_crc_ok = '0') else '0';
  -- A payload error is only meaningful on a Data Packet with a good header.
  -- Claiming one after a header failure would assert knowledge that there WAS
  -- a payload -- which requires the header.
  pe <= '1' when (pkt_valid = '1' and hdr_crc_ok = '1' and ptype = PKT_DP
                  and payload_present = '1' and payload_crc_ok = '0')
        else '0';

  pkt_type <= pkt_code(ptype);
  route    <= route_code(rt);

  hdr_error     <= he;
  payload_error <= pe;

  -- TWO DIFFERENT RECOVERIES, mutually exclusive by construction: one needs a
  -- header the other one does not have.
  link_retry_req   <= he;
  protocol_nak_req <= pe;

  -- An ITP is broadcast and never acknowledged -- an ACK for a timestamp is
  -- pointless, since it is stale the moment it is questioned.
  ack_expected <= '1' when (ptype = PKT_TP or ptype = PKT_DP) else '0';

  counters : process (clk, rst_n)
  begin
    if rst_n = '0' then
      he_r <= (others => '0');
      pe_r <= (others => '0');
      rs_r <= (others => '0');
      dl_r <= (others => '0');
    elsif rising_edge(clk) then
      if pkt_valid = '1' then
        if he = '1' then
          he_r <= he_r + 1;
        end if;
        if pe = '1' then
          pe_r <= pe_r + 1;
        end if;
        if ptype = PKT_RSVD then
          rs_r <= rs_r + 1;
        end if;
        if rt /= ROUTE_DISCARD and rt /= ROUTE_NONE then
          dl_r <= dl_r + 1;
        end if;
      end if;
    end if;
  end process;

  hdr_errors     <= std_logic_vector(he_r);
  payload_errors <= std_logic_vector(pe_r);
  reserved_types <= std_logic_vector(rs_r);
  delivered      <= std_logic_vector(dl_r);
end architecture;

`timescale 1ns/1ps
module tb_pk_v;
  reg clk=0, rst_n=0;
  reg pv=0, hco=0, pp=0, pco=0;
  reg [4:0] ht=0;
  wire [2:0] pkt_type;
  wire [1:0] route;
  wire hdr_error, payload_error, link_retry_req, protocol_nak_req;
  wire ack_expected;
  wire [31:0] hdr_errors, payload_errors, reserved_types, delivered;
  always #5 clk=~clk;

  usb3_packet_decode dut (
    .clk(clk), .rst_n(rst_n), .pkt_valid(pv), .hdr_type(ht),
    .hdr_crc_ok(hco), .payload_present(pp), .payload_crc_ok(pco),
    .pkt_type(pkt_type), .route(route), .hdr_error(hdr_error),
    .payload_error(payload_error), .link_retry_req(link_retry_req),
    .protocol_nak_req(protocol_nak_req), .ack_expected(ack_expected),
    .hdr_errors(hdr_errors), .payload_errors(payload_errors),
    .reserved_types(reserved_types), .delivered(delivered));

  localparam [2:0] P_NONE=0, P_LMP=1, P_TP=2, P_DP=3, P_ITP=4,
                   P_RSVD=5, P_UNK=6;
  localparam [1:0] R_NONE=0, R_LINK=1, R_PROTO=2, R_DISCARD=3;

  integer errors=0, i, t, c, q, r, v;
  integer n_exh=0;
  integer n_pt [0:6];
  integer n_rt [0:3];
  integer m_he, m_pe, m_rs, m_dl;

  task check(input cond, input [639:0] msg);
    begin if (!cond) begin errors=errors+1;
      if (errors <= 25)
        $display("  FAIL: %0s (pv=%b ht=%0h crc=%b pp=%b pcrc=%b | type=%0d route=%0d he=%b pe=%b, t=%0t)",
                 msg, pv, ht, hco, pp, pco, pkt_type, route, hdr_error,
                 payload_error, $time);
    end end
  endtask

  task check_comb;
    integer e_type, e_route;
    reg e_he, e_pe, e_ack;
    begin
      // The model decides the type with a case over the four defined
      // encodings rather than a chain of ternaries -- a different route.
      if (!pv)        e_type = P_NONE;
      else if (!hco)  e_type = P_UNK;
      else case (ht)
        5'h00:   e_type = P_LMP;
        5'h04:   e_type = P_TP;
        5'h08:   e_type = P_DP;
        5'h0C:   e_type = P_ITP;
        default: e_type = P_RSVD;
      endcase

      if (e_type == P_NONE)                            e_route = R_NONE;
      else if (e_type == P_UNK || e_type == P_RSVD)    e_route = R_DISCARD;
      else if (e_type == P_LMP)                        e_route = R_LINK;
      else                                             e_route = R_PROTO;

      e_he  = pv && !hco;
      e_pe  = pv && hco && (e_type == P_DP) && pp && !pco;
      e_ack = (e_type == P_TP) || (e_type == P_DP);

      check(pkt_type         === e_type[2:0],  "pkt_type matches the model");
      check(route            === e_route[1:0], "route matches the model");
      check(hdr_error        === e_he,         "hdr_error matches the model");
      check(payload_error    === e_pe,         "payload_error matches the model");
      check(link_retry_req   === e_he,         "link retry follows the header");
      check(protocol_nak_req === e_pe,         "protocol NAK follows the payload");
      check(ack_expected     === e_ack,        "only TP and DP are acknowledged");

      // ---- SAFETY PROPERTIES, independent of the model ----
      // 1. THE one that matters: with a bad header CRC the type is NOT
      //    decoded. Acting on the type field of a header a CRC has just
      //    declared corrupt routes a packet on untrustworthy bits.
      if (pv && !hco)
        check(pkt_type === P_UNK,
              "a corrupt header was decoded into a packet type anyway");
      // 2. And such a packet reaches nobody.
      if (pv && !hco)
        check(route === R_DISCARD,
              "a packet with a corrupt header was routed somewhere");
      // 3. The two recoveries are mutually exclusive: one needs a header
      //    the other does not have.
      check(!(link_retry_req && protocol_nak_req),
            "a link retry and a protocol NAK requested for one packet");
      // 4. A payload error is never claimed without a good header, because
      //    knowing there WAS a payload requires the header.
      check(!payload_error || hco,
            "a payload error claimed with no trustworthy header");
      // 5. Nothing is routed when no packet is present.
      if (!pv) check(route === R_NONE, "a route asserted with no packet");

      if (e_type >= 0 && e_type <= 6) n_pt[e_type] = n_pt[e_type] + 1;
      if (e_route >= 0 && e_route <= 3) n_rt[e_route] = n_rt[e_route] + 1;
    end
  endtask

  task step;
    begin
      #1;
      check_comb;
      if (pv) begin
        if (hdr_error)           m_he = m_he + 1;
        if (payload_error)       m_pe = m_pe + 1;
        if (pkt_type === P_RSVD) m_rs = m_rs + 1;
        if (route !== R_DISCARD && route !== R_NONE) m_dl = m_dl + 1;
      end
      @(posedge clk); #1;
      check(hdr_errors     === m_he[31:0], "hdr_errors matches the model");
      check(payload_errors === m_pe[31:0], "payload_errors matches the model");
      check(reserved_types === m_rs[31:0], "reserved_types matches the model");
      check(delivered      === m_dl[31:0], "delivered matches the model");
    end
  endtask

  task hard_reset;
    begin
      rst_n=0; pv=0; ht=0; hco=0; pp=0; pco=0;
      @(posedge clk); #1; @(posedge clk); #1; rst_n=1; #1;
      m_he=0; m_pe=0; m_rs=0; m_dl=0;
    end
  endtask

  initial begin
    for (i=0;i<7;i=i+1) n_pt[i]=0;
    for (i=0;i<4;i=i+1) n_rt[i]=0;
    hard_reset;
    check(pkt_type === P_NONE, "no packet, no type");
    check(route === R_NONE, "and no route");

    // ===== A. EXHAUSTIVE over the whole decode =====
    // 32 header-type encodings x header CRC ok/bad x payload present/absent
    // x payload CRC ok/bad x packet valid/not = 512 points, which is the
    // ENTIRE decision surface including all 28 reserved type encodings.
    for (v=0; v<2; v=v+1)
     for (t=0; t<32; t=t+1)
      for (c=0; c<2; c=c+1)
       for (q=0; q<2; q=q+1)
        for (r=0; r<2; r=r+1) begin
          pv=v[0]; ht=t[4:0]; hco=c[0]; pp=q[0]; pco=r[0];
          step;
          n_exh = n_exh + 1;
        end
    $display("  exhaustive packet-decode sweep: %0d of %0d points verified",
             n_exh, 2*32*2*2*2);

    // ===== B. directed: the four types and the two failures =====
    hard_reset;
    pv=1; ht=5'h00; hco=1; pp=0; pco=1; step;
    check(pkt_type === P_LMP, "type 0x00 is a Link Management Packet");
    check(route === R_LINK, "and it stays at the LINK layer");
    check(!ack_expected, "LMPs are not acknowledged this way");

    pv=1; ht=5'h04; hco=1; pp=0; pco=1; step;
    check(pkt_type === P_TP, "type 0x04 is a Transaction Packet");
    check(route === R_PROTO, "which goes up to the protocol layer");
    check(ack_expected, "and is acknowledged");

    pv=1; ht=5'h0C; hco=1; pp=0; pco=1; step;
    check(pkt_type === P_ITP, "type 0x0C is an Isochronous Timestamp Packet");
    check(route === R_PROTO, "which is delivered");
    check(!ack_expected,
          "but NEVER acknowledged: a timestamp is stale once questioned");

    // a Data Packet with a bad payload still routes
    pv=1; ht=5'h08; hco=1; pp=1; pco=0; step;
    check(pkt_type === P_DP, "type 0x08 is a Data Packet");
    check(payload_error, "its payload CRC failed");
    check(route === R_PROTO,
          "and it is STILL routed: the header says which endpoint to re-ask");
    check(protocol_nak_req, "with a PROTOCOL-level NAK");
    check(!link_retry_req, "and NOT a link retry");

    // a bad header is a different problem entirely
    pv=1; ht=5'h08; hco=0; pp=1; pco=1; step;
    check(pkt_type === P_UNK,
          "a corrupt header yields UNKNOWN, not the type its bits spell");
    check(route === R_DISCARD, "and the packet reaches nobody");
    check(link_retry_req, "recovery is a LINK retry");
    check(!protocol_nak_req, "and not a protocol NAK");
    check(!payload_error,
          "and no payload error is claimed: there is no trustworthy header");

    // a reserved type has a GOOD CRC and an uninterpretable type
    pv=1; ht=5'h11; hco=1; pp=0; pco=1; step;
    check(pkt_type === P_RSVD, "an undefined encoding is RESERVED");
    check(route === R_DISCARD, "and is discarded");
    check(!link_retry_req,
          "without a link retry: retrying returns the same reserved value");
    check(!hdr_error, "and it is not a header error -- the CRC was fine");

    // ===== C. randomised =====
    for (i=0;i<40000;i=i+1) begin
      pv=({$random}%8)!=0;
      // bias toward the four defined encodings so the reserved path is
      // exercised without swamping everything else
      if (({$random}%3)==0) ht = {$random}%32;
      else ht = (({$random}%4)*4);
      hco=({$random}%8)!=0; pp=({$random}%2); pco=({$random}%4)!=0;
      step;
    end

    for (i=0;i<7;i=i+1)
      check(n_pt[i] > 0, "every packet-type outcome was reached");
    for (i=0;i<4;i=i+1)
      check(n_rt[i] > 0, "every routing outcome was reached");

    $display("");
    $display("  REACH: exhaustive=%0d | types: none=%0d lmp=%0d tp=%0d dp=%0d itp=%0d rsvd=%0d unknown=%0d",
             n_exh, n_pt[0], n_pt[1], n_pt[2], n_pt[3], n_pt[4], n_pt[5],
             n_pt[6]);
    $display("  ROUTES: none=%0d link=%0d protocol=%0d discard=%0d | hdr-err=%0d payload-err=%0d reserved=%0d delivered=%0d",
             n_rt[0], n_rt[1], n_rt[2], n_rt[3], hdr_errors, payload_errors,
             reserved_types, delivered);
    $display("  [Verilog] usb3_packet_decode: %0d errors", errors);
    $display("  [Verilog] %0s", errors==0 ? "PASS" : "FAIL");
    $display("");
    $finish;
  end
endmodule

`timescale 1ns/1ps
module tb_pk_sv;
  import usb3_packet_pkg::*;

  logic clk=0, rst_n=0;
  logic pv=0, hco=0, pp=0, pco=0;
  logic [4:0] ht=0;
  pkt_type_e pkt_type;
  route_e    route;
  logic hdr_error, payload_error, link_retry_req, protocol_nak_req;
  logic ack_expected;
  logic [31:0] hdr_errors, payload_errors, reserved_types, delivered;
  always #5 clk=~clk;

  usb3_packet_decode dut (
    .clk, .rst_n, .pkt_valid(pv), .hdr_type(ht), .hdr_crc_ok(hco),
    .payload_present(pp), .payload_crc_ok(pco), .pkt_type, .route,
    .hdr_error, .payload_error, .link_retry_req, .protocol_nak_req,
    .ack_expected, .hdr_errors, .payload_errors, .reserved_types, .delivered);

  int errors=0, i, t, c, q, r, v;
  int n_exh=0;
  int n_pt [7];
  int n_rt [4];
  int m_he, m_pe, m_rs, m_dl;

  // Icarus will not call .name() on a net, so the enum outputs are copied
  // into variables of the same type before being printed.
  task automatic check(input bit cond, input string msg);
    pkt_type_e pt_v;
    route_e    rt_v;
    if (!cond) begin
      errors++;
      pt_v = pkt_type;
      rt_v = route;
      if (errors <= 25)
        $display("  FAIL: %0s (pv=%b ht=%0h crc=%b pp=%b pcrc=%b | type=%s route=%s, t=%0t)",
                 msg, pv, ht, hco, pp, pco, pt_v.name(), rt_v.name(), $time);
    end
  endtask

  task automatic check_comb;
    pkt_type_e e_type;
    route_e    e_route;
    bit e_he, e_pe, e_ack;
    begin
      // The model reaches the same answer by a different route: a priority
      // chain of comparisons rather than the design's case statement.
      if (!pv)                    e_type = PKT_NONE;
      else if (!hco)              e_type = PKT_UNKNOWN;
      else if (ht == 5'h00)       e_type = PKT_LMP;
      else if (ht == 5'h04)       e_type = PKT_TP;
      else if (ht == 5'h08)       e_type = PKT_DP;
      else if (ht == 5'h0C)       e_type = PKT_ITP;
      else                        e_type = PKT_RSVD;

      if (e_type == PKT_NONE)                                 e_route = ROUTE_NONE;
      else if (e_type == PKT_UNKNOWN || e_type == PKT_RSVD)   e_route = ROUTE_DISCARD;
      else if (e_type == PKT_LMP)                             e_route = ROUTE_LINK;
      else                                                    e_route = ROUTE_PROTOCOL;

      e_he  = pv && !hco;
      e_pe  = pv && hco && (e_type == PKT_DP) && pp && !pco;
      e_ack = (e_type == PKT_TP) || (e_type == PKT_DP);

      check(pkt_type         === e_type,  "pkt_type matches the model");
      check(route            === e_route, "route matches the model");
      check(hdr_error        === e_he,    "hdr_error matches the model");
      check(payload_error    === e_pe,    "payload_error matches the model");
      check(link_retry_req   === e_he,    "link retry follows the header");
      check(protocol_nak_req === e_pe,    "protocol NAK follows the payload");
      check(ack_expected     === e_ack,   "only TP and DP are acknowledged");

      // ---- SAFETY PROPERTIES, independent of the model ----
      // 1. THE one that matters: with a bad header CRC the type is NOT
      //    decoded. Acting on the type field of a header a CRC has just
      //    declared corrupt routes a packet on untrustworthy bits.
      if (pv && !hco)
        check(pkt_type === PKT_UNKNOWN,
              "a corrupt header was decoded into a packet type anyway");
      // 2. And such a packet reaches nobody.
      if (pv && !hco)
        check(route === ROUTE_DISCARD,
              "a packet with a corrupt header was routed somewhere");
      // 3. The two recoveries are mutually exclusive: one needs a header the
      //    other does not have.
      check(!(link_retry_req && protocol_nak_req),
            "a link retry and a protocol NAK requested for one packet");
      // 4. A payload error is never claimed without a good header.
      check(!payload_error || hco,
            "a payload error claimed with no trustworthy header");
      // 5. Nothing is routed when no packet is present.
      if (!pv) check(route === ROUTE_NONE, "a route asserted with no packet");

      n_pt[int'(e_type)]  = n_pt[int'(e_type)] + 1;
      n_rt[int'(e_route)] = n_rt[int'(e_route)] + 1;
    end
  endtask

  task automatic step;
    begin
      #1;
      check_comb;
      if (pv) begin
        if (hdr_error)              m_he++;
        if (payload_error)          m_pe++;
        if (pkt_type === PKT_RSVD)  m_rs++;
        if (route !== ROUTE_DISCARD && route !== ROUTE_NONE) m_dl++;
      end
      @(posedge clk); #1;
      check(hdr_errors     === 32'(m_he), "hdr_errors matches the model");
      check(payload_errors === 32'(m_pe), "payload_errors matches the model");
      check(reserved_types === 32'(m_rs), "reserved_types matches the model");
      check(delivered      === 32'(m_dl), "delivered matches the model");
    end
  endtask

  task automatic hard_reset;
    begin
      rst_n=0; pv=0; ht=0; hco=0; pp=0; pco=0;
      @(posedge clk); #1; @(posedge clk); #1; rst_n=1; #1;
      m_he=0; m_pe=0; m_rs=0; m_dl=0;
    end
  endtask

  initial begin
    foreach (n_pt[i]) n_pt[i]=0;
    foreach (n_rt[i]) n_rt[i]=0;
    hard_reset;
    check(pkt_type === PKT_NONE, "no packet, no type");
    check(route === ROUTE_NONE, "and no route");

    // ===== A. EXHAUSTIVE over the whole decode =====
    // 32 header-type encodings x header CRC ok/bad x payload present/absent
    // x payload CRC ok/bad x packet valid/not = 512 points -- the ENTIRE
    // decision surface, including all 28 reserved type encodings.
    for (v=0; v<2; v++)
     for (t=0; t<32; t++)
      for (c=0; c<2; c++)
       for (q=0; q<2; q++)
        for (r=0; r<2; r++) begin
          pv=v[0]; ht=t[4:0]; hco=c[0]; pp=q[0]; pco=r[0];
          step;
          n_exh++;
        end
    $display("  exhaustive packet-decode sweep: %0d of %0d points verified",
             n_exh, 2*32*2*2*2);

    // ===== B. directed: the four types and the two failures =====
    hard_reset;
    pv=1; ht=5'h00; hco=1; pp=0; pco=1; step;
    check(pkt_type === PKT_LMP, "type 0x00 is a Link Management Packet");
    check(route === ROUTE_LINK, "and it stays at the LINK layer");
    check(!ack_expected, "LMPs are not acknowledged this way");

    pv=1; ht=5'h04; hco=1; pp=0; pco=1; step;
    check(pkt_type === PKT_TP, "type 0x04 is a Transaction Packet");
    check(route === ROUTE_PROTOCOL, "which goes up to the protocol layer");
    check(ack_expected, "and is acknowledged");

    pv=1; ht=5'h0C; hco=1; pp=0; pco=1; step;
    check(pkt_type === PKT_ITP, "type 0x0C is an Isochronous Timestamp Packet");
    check(route === ROUTE_PROTOCOL, "which is delivered");
    check(!ack_expected,
          "but NEVER acknowledged: a timestamp is stale once questioned");

    // a Data Packet with a bad payload still routes
    pv=1; ht=5'h08; hco=1; pp=1; pco=0; step;
    check(pkt_type === PKT_DP, "type 0x08 is a Data Packet");
    check(payload_error, "its payload CRC failed");
    check(route === ROUTE_PROTOCOL,
          "and it is STILL routed: the header says which endpoint to re-ask");
    check(protocol_nak_req, "with a PROTOCOL-level NAK");
    check(!link_retry_req, "and NOT a link retry");

    // a bad header is a different problem entirely
    pv=1; ht=5'h08; hco=0; pp=1; pco=1; step;
    check(pkt_type === PKT_UNKNOWN,
          "a corrupt header yields UNKNOWN, not the type its bits spell");
    check(route === ROUTE_DISCARD, "and the packet reaches nobody");
    check(link_retry_req, "recovery is a LINK retry");
    check(!protocol_nak_req, "and not a protocol NAK");
    check(!payload_error,
          "and no payload error is claimed: there is no trustworthy header");

    // a reserved type has a GOOD CRC and an uninterpretable type
    pv=1; ht=5'h11; hco=1; pp=0; pco=1; step;
    check(pkt_type === PKT_RSVD, "an undefined encoding is RESERVED");
    check(route === ROUTE_DISCARD, "and is discarded");
    check(!link_retry_req,
          "without a link retry: retrying returns the same reserved value");
    check(!hdr_error, "and it is not a header error -- the CRC was fine");

    // ===== C. randomised =====
    for (i=0;i<40000;i++) begin
      pv=($urandom%8)!=0;
      if (($urandom%3)==0) ht = $urandom%32;
      else ht = 5'(($urandom%4)*4);
      hco=($urandom%8)!=0; pp=$urandom%2; pco=($urandom%4)!=0;
      step;
    end

    foreach (n_pt[i]) check(n_pt[i] > 0, "every packet-type outcome was reached");
    foreach (n_rt[i]) check(n_rt[i] > 0, "every routing outcome was reached");

    $display("");
    $display("  REACH: exhaustive=%0d | types: none=%0d lmp=%0d tp=%0d dp=%0d itp=%0d rsvd=%0d unknown=%0d",
             n_exh, n_pt[0], n_pt[1], n_pt[2], n_pt[3], n_pt[4], n_pt[5], n_pt[6]);
    $display("  ROUTES: none=%0d link=%0d protocol=%0d discard=%0d | hdr-err=%0d payload-err=%0d reserved=%0d delivered=%0d",
             n_rt[0], n_rt[1], n_rt[2], n_rt[3], hdr_errors, payload_errors,
             reserved_types, delivered);
    $display("  [SystemVerilog] usb3_packet_decode: %0d errors", errors);
    $display("  [SystemVerilog] %0s", errors==0 ? "PASS" : "FAIL");
    $display("");
    $finish;
  end
endmodule

library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;
use ieee.math_real.all;
use work.usb3_packet_pkg.all;

entity tb_pk_vhdl is
end entity;

architecture sim of tb_pk_vhdl is
  signal clk   : std_logic := '0';
  signal rst_n : std_logic := '0';
  signal pv, hco, pp, pco : std_logic := '0';
  signal ht : std_logic_vector(4 downto 0) := (others => '0');

  signal pkt_type : std_logic_vector(2 downto 0);
  signal route    : std_logic_vector(1 downto 0);
  signal hdr_error, payload_error, link_retry_req : std_logic;
  signal protocol_nak_req, ack_expected : std_logic;
  signal hdr_errors, payload_errors, reserved_types, delivered
       : std_logic_vector(31 downto 0);

  signal running : boolean := true;

  type cnt7_t is array (0 to 6) of integer;
  type cnt4_t is array (0 to 3) of integer;
begin
  clk <= not clk after 5 ns when running else '0';

  dut : entity work.usb3_packet_decode
    port map (clk => clk, rst_n => rst_n, pkt_valid => pv, hdr_type => ht,
              hdr_crc_ok => hco, payload_present => pp, payload_crc_ok => pco,
              pkt_type => pkt_type, route => route, hdr_error => hdr_error,
              payload_error => payload_error, link_retry_req => link_retry_req,
              protocol_nak_req => protocol_nak_req,
              ack_expected => ack_expected, hdr_errors => hdr_errors,
              payload_errors => payload_errors,
              reserved_types => reserved_types, delivered => delivered);

  stim : process
    variable seed1 : positive := 8867;
    variable seed2 : positive := 3391;
    variable r1    : real;

    -- VHDL-2008 requires a shared variable to have a protected type, so the
    -- bookkeeping lives inside the single stimulus process instead.
    variable errors : integer := 0;
    variable n_pt   : cnt7_t  := (others => 0);
    variable n_rt   : cnt4_t  := (others => 0);
    variable n_exh  : integer := 0;
    variable m_he, m_pe, m_rs, m_dl : integer := 0;

    procedure check(cond : boolean; msg : string) is
    begin
      if not cond then
        errors := errors + 1;
        if errors <= 25 then
          report "  FAIL: " & msg
               & " (pv=" & std_logic'image(pv)(2)
               & " ht=" & integer'image(to_integer(unsigned(ht)))
               & " crc=" & std_logic'image(hco)(2)
               & " pp=" & std_logic'image(pp)(2)
               & " pcrc=" & std_logic'image(pco)(2)
               & " | type=" & integer'image(to_integer(unsigned(pkt_type)))
               & " route=" & integer'image(to_integer(unsigned(route)))
               & ")" severity note;
        end if;
      end if;
    end procedure;

    procedure rnd(variable v : out integer; m : integer) is
    begin
      uniform(seed1, seed2, r1);
      v := integer(floor(r1 * real(m)));
    end procedure;

    procedure check_comb is
      variable e_type  : pkt_type_t;
      variable e_route : route_t;
      variable e_he, e_pe, e_ack : std_logic;
    begin
      -- The model reaches the same answer by a different route: a chain of
      -- comparisons rather than the design's case statement.
      if pv = '0' then
        e_type := PKT_NONE;
      elsif hco = '0' then
        e_type := PKT_UNKNOWN;
      elsif ht = "00000" then e_type := PKT_LMP;
      elsif ht = "00100" then e_type := PKT_TP;
      elsif ht = "01000" then e_type := PKT_DP;
      elsif ht = "01100" then e_type := PKT_ITP;
      else                    e_type := PKT_RSVD;
      end if;

      if e_type = PKT_NONE then
        e_route := ROUTE_NONE;
      elsif e_type = PKT_UNKNOWN or e_type = PKT_RSVD then
        e_route := ROUTE_DISCARD;
      elsif e_type = PKT_LMP then
        e_route := ROUTE_LINK;
      else
        e_route := ROUTE_PROTOCOL;
      end if;

      if pv = '1' and hco = '0' then e_he := '1'; else e_he := '0'; end if;
      if pv = '1' and hco = '1' and e_type = PKT_DP and pp = '1'
         and pco = '0' then
        e_pe := '1';
      else
        e_pe := '0';
      end if;
      if e_type = PKT_TP or e_type = PKT_DP then
        e_ack := '1';
      else
        e_ack := '0';
      end if;

      check(pkt_type = pkt_code(e_type),   "pkt_type matches the model");
      check(route = route_code(e_route),   "route matches the model");
      check(hdr_error = e_he,              "hdr_error matches the model");
      check(payload_error = e_pe,          "payload_error matches the model");
      check(link_retry_req = e_he,         "link retry follows the header");
      check(protocol_nak_req = e_pe,       "protocol NAK follows the payload");
      check(ack_expected = e_ack,          "only TP and DP are acknowledged");

      -- ---- SAFETY PROPERTIES, independent of the model ----
      -- 1. THE one that matters: with a bad header CRC the type is NOT
      --    decoded. Acting on the type field of a header a CRC has just
      --    declared corrupt routes a packet on untrustworthy bits.
      if pv = '1' and hco = '0' then
        check(pkt_type = pkt_code(PKT_UNKNOWN),
              "a corrupt header was decoded into a packet type anyway");
      -- 2. And such a packet reaches nobody.
        check(route = route_code(ROUTE_DISCARD),
              "a packet with a corrupt header was routed somewhere");
      end if;
      -- 3. The two recoveries are mutually exclusive.
      check(not (link_retry_req = '1' and protocol_nak_req = '1'),
            "a link retry and a protocol NAK requested for one packet");
      -- 4. A payload error is never claimed without a good header.
      check(payload_error = '0' or hco = '1',
            "a payload error claimed with no trustworthy header");
      -- 5. Nothing is routed when no packet is present.
      if pv = '0' then
        check(route = route_code(ROUTE_NONE),
              "a route asserted with no packet");
      end if;

      n_pt(pkt_type_t'pos(e_type)) := n_pt(pkt_type_t'pos(e_type)) + 1;
      n_rt(route_t'pos(e_route))   := n_rt(route_t'pos(e_route)) + 1;
    end procedure;

    procedure step is
    begin
      wait for 1 ns;
      check_comb;
      if pv = '1' then
        if hdr_error = '1' then m_he := m_he + 1; end if;
        if payload_error = '1' then m_pe := m_pe + 1; end if;
        if pkt_type = pkt_code(PKT_RSVD) then m_rs := m_rs + 1; end if;
        if route /= route_code(ROUTE_DISCARD)
           and route /= route_code(ROUTE_NONE) then
          m_dl := m_dl + 1;
        end if;
      end if;
      wait until rising_edge(clk);
      wait for 1 ns;
      check(hdr_errors = std_logic_vector(to_unsigned(m_he, 32)),
            "hdr_errors matches the model");
      check(payload_errors = std_logic_vector(to_unsigned(m_pe, 32)),
            "payload_errors matches the model");
      check(reserved_types = std_logic_vector(to_unsigned(m_rs, 32)),
            "reserved_types matches the model");
      check(delivered = std_logic_vector(to_unsigned(m_dl, 32)),
            "delivered matches the model");
    end procedure;

    procedure hard_reset is
    begin
      rst_n <= '0'; pv <= '0'; ht <= (others => '0');
      hco <= '0'; pp <= '0'; pco <= '0';
      wait until rising_edge(clk); wait for 1 ns;
      wait until rising_edge(clk); wait for 1 ns;
      rst_n <= '1'; wait for 1 ns;
      m_he := 0; m_pe := 0; m_rs := 0; m_dl := 0;
    end procedure;

    variable iv : integer;
  begin
    hard_reset;
    check(pkt_type = pkt_code(PKT_NONE), "no packet, no type");
    check(route = route_code(ROUTE_NONE), "and no route");

    -- ===== A. EXHAUSTIVE over the whole decode =====
    -- 32 header-type encodings x header CRC ok/bad x payload present/absent
    -- x payload CRC ok/bad x packet valid/not = 512 points -- the ENTIRE
    -- decision surface, including all 28 reserved type encodings.
    for v in 0 to 1 loop
      for t in 0 to 31 loop
        for c in 0 to 1 loop
          for q in 0 to 1 loop
            for r in 0 to 1 loop
              if v = 1 then pv <= '1'; else pv <= '0'; end if;
              ht <= std_logic_vector(to_unsigned(t, 5));
              if c = 1 then hco <= '1'; else hco <= '0'; end if;
              if q = 1 then pp <= '1';  else pp <= '0';  end if;
              if r = 1 then pco <= '1'; else pco <= '0'; end if;
              step;
              n_exh := n_exh + 1;
            end loop;
          end loop;
        end loop;
      end loop;
    end loop;
    report "  exhaustive packet-decode sweep: " & integer'image(n_exh)
         & " of 512 points verified" severity note;

    -- ===== B. directed: the four types and the two failures =====
    hard_reset;
    pv <= '1'; ht <= "00000"; hco <= '1'; pp <= '0'; pco <= '1'; step;
    check(pkt_type = pkt_code(PKT_LMP),
          "type 0x00 is a Link Management Packet");
    check(route = route_code(ROUTE_LINK), "and it stays at the LINK layer");
    check(ack_expected = '0', "LMPs are not acknowledged this way");

    pv <= '1'; ht <= "00100"; hco <= '1'; pp <= '0'; pco <= '1'; step;
    check(pkt_type = pkt_code(PKT_TP), "type 0x04 is a Transaction Packet");
    check(route = route_code(ROUTE_PROTOCOL),
          "which goes up to the protocol layer");
    check(ack_expected = '1', "and is acknowledged");

    pv <= '1'; ht <= "01100"; hco <= '1'; pp <= '0'; pco <= '1'; step;
    check(pkt_type = pkt_code(PKT_ITP),
          "type 0x0C is an Isochronous Timestamp Packet");
    check(route = route_code(ROUTE_PROTOCOL), "which is delivered");
    check(ack_expected = '0',
          "but NEVER acknowledged: a timestamp is stale once questioned");

    -- a Data Packet with a bad payload still routes
    pv <= '1'; ht <= "01000"; hco <= '1'; pp <= '1'; pco <= '0'; step;
    check(pkt_type = pkt_code(PKT_DP), "type 0x08 is a Data Packet");
    check(payload_error = '1', "its payload CRC failed");
    check(route = route_code(ROUTE_PROTOCOL),
          "and it is STILL routed: the header says which endpoint to re-ask");
    check(protocol_nak_req = '1', "with a PROTOCOL-level NAK");
    check(link_retry_req = '0', "and NOT a link retry");

    -- a bad header is a different problem entirely
    pv <= '1'; ht <= "01000"; hco <= '0'; pp <= '1'; pco <= '1'; step;
    check(pkt_type = pkt_code(PKT_UNKNOWN),
          "a corrupt header yields UNKNOWN, not the type its bits spell");
    check(route = route_code(ROUTE_DISCARD), "and the packet reaches nobody");
    check(link_retry_req = '1', "recovery is a LINK retry");
    check(protocol_nak_req = '0', "and not a protocol NAK");
    check(payload_error = '0',
          "and no payload error is claimed: there is no trustworthy header");

    -- a reserved type has a GOOD CRC and an uninterpretable type
    pv <= '1'; ht <= "10001"; hco <= '1'; pp <= '0'; pco <= '1'; step;
    check(pkt_type = pkt_code(PKT_RSVD), "an undefined encoding is RESERVED");
    check(route = route_code(ROUTE_DISCARD), "and is discarded");
    check(link_retry_req = '0',
          "without a link retry: retrying returns the same reserved value");
    check(hdr_error = '0',
          "and it is not a header error -- the CRC was fine");

    -- ===== C. randomised =====
    for i in 0 to 39999 loop
      rnd(iv, 8); if iv /= 0 then pv <= '1'; else pv <= '0'; end if;
      rnd(iv, 3);
      if iv = 0 then
        rnd(iv, 32);
        ht <= std_logic_vector(to_unsigned(iv, 5));
      else
        rnd(iv, 4);
        ht <= std_logic_vector(to_unsigned(iv * 4, 5));
      end if;
      rnd(iv, 8); if iv /= 0 then hco <= '1'; else hco <= '0'; end if;
      rnd(iv, 2); if iv = 1 then pp <= '1'; else pp <= '0'; end if;
      rnd(iv, 4); if iv /= 0 then pco <= '1'; else pco <= '0'; end if;
      step;
    end loop;

    for i in 0 to 6 loop
      check(n_pt(i) > 0, "every packet-type outcome was reached");
    end loop;
    for i in 0 to 3 loop
      check(n_rt(i) > 0, "every routing outcome was reached");
    end loop;

    report "  REACH: exhaustive=" & integer'image(n_exh)
         & " | types: none=" & integer'image(n_pt(0))
         & " lmp=" & integer'image(n_pt(1))
         & " tp=" & integer'image(n_pt(2))
         & " dp=" & integer'image(n_pt(3))
         & " itp=" & integer'image(n_pt(4))
         & " rsvd=" & integer'image(n_pt(5))
         & " unknown=" & integer'image(n_pt(6)) severity note;
    report "  ROUTES: none=" & integer'image(n_rt(0))
         & " link=" & integer'image(n_rt(1))
         & " protocol=" & integer'image(n_rt(2))
         & " discard=" & integer'image(n_rt(3))
         & " | hdr-err=" & integer'image(to_integer(unsigned(hdr_errors)))
         & " payload-err=" & integer'image(to_integer(unsigned(payload_errors)))
         & " reserved=" & integer'image(to_integer(unsigned(reserved_types)))
         & " delivered=" & integer'image(to_integer(unsigned(delivered)))
         severity note;
    report "  [VHDL] usb3_packet_decode: " & integer'image(errors) & " errors"
         severity note;
    if errors = 0 then
      report "  [VHDL] PASS" severity note;
    else
      report "  [VHDL] FAIL" severity failure;
    end if;
    running <= false;
    wait;
  end process;
end architecture;

class usb3_pkt_item extends uvm_sequence_item;
  `uvm_object_utils(usb3_pkt_item)

  rand bit        pkt_valid;
  rand bit [4:0]  hdr_type;
  rand bit        hdr_crc_ok;
  rand bit        payload_present;
  rand bit        payload_crc_ok;

  // The four defined encodings, so a "legal" packet can be asked for
  // without the sequence having to know the numbers.
  constraint c_defined_type {
    soft hdr_type inside {5'h00, 5'h04, 5'h08, 5'h0C};
  }

  // Errors are rare in the field. Making them rare here too means the
  // ordinary paths get exercised; the directed sequences below override
  // this when they want the error path specifically.
  constraint c_errors_rare {
    hdr_crc_ok     dist {1 := 95, 0 := 5};
    payload_crc_ok dist {1 := 95, 0 := 5};
  }

  // Only a Data Packet carries a payload.
  constraint c_payload_only_dp {
    (hdr_type != 5'h08) -> payload_present == 0;
  }

  function new(string name = "usb3_pkt_item");
    super.new(name);
  endfunction

  function string convert2string();
    return $sformatf("valid=%0b type=0x%02h hcrc=%0b pp=%0b pcrc=%0b",
                     pkt_valid, hdr_type, hdr_crc_ok, payload_present,
                     payload_crc_ok);
  endfunction
endclass

// Ordinary traffic: legal types, errors at field-realistic rates.
class nominal_traffic_seq extends uvm_sequence #(usb3_pkt_item);
  `uvm_object_utils(nominal_traffic_seq)
  function new(string name = "nominal_traffic_seq"); super.new(name); endfunction

  task body();
    repeat (2000) begin
      usb3_pkt_item it = usb3_pkt_item::type_id::create("it");
      start_item(it);
      if (!it.randomize() with { pkt_valid dist {1 := 90, 0 := 10}; })
        `uvm_error("RAND", "nominal randomize failed")
      finish_item(it);
    end
  endtask
endclass

// THE sequence for this chapter: every packet has a corrupt header, and the
// type field is randomised over all 32 encodings. A receiver that decodes
// before validating will route these somewhere, and the scoreboard will see
// it. This is the K1 mutation's natural predator.
class corrupt_header_seq extends uvm_sequence #(usb3_pkt_item);
  `uvm_object_utils(corrupt_header_seq)
  function new(string name = "corrupt_header_seq"); super.new(name); endfunction

  task body();
    repeat (500) begin
      usb3_pkt_item it = usb3_pkt_item::type_id::create("it");
      start_item(it);
      // c_defined_type is soft, so this override is legal and the full
      // 32-encoding space is explored under a failing CRC.
      if (!it.randomize() with { pkt_valid  == 1;
                                 hdr_crc_ok == 0;
                                 hdr_type inside {[0:31]}; })
        `uvm_error("RAND", "corrupt-header randomize failed")
      finish_item(it);
    end
  endtask
endclass

// Reserved encodings under a GOOD CRC -- the third case from section 5.
// The property under test is that these are discarded WITHOUT a retry.
class reserved_type_seq extends uvm_sequence #(usb3_pkt_item);
  `uvm_object_utils(reserved_type_seq)
  function new(string name = "reserved_type_seq"); super.new(name); endfunction

  task body();
    repeat (500) begin
      usb3_pkt_item it = usb3_pkt_item::type_id::create("it");
      start_item(it);
      if (!it.randomize() with { pkt_valid  == 1;
                                 hdr_crc_ok == 1;
                                 !(hdr_type inside {5'h00, 5'h04,
                                                    5'h08, 5'h0C}); })
        `uvm_error("RAND", "reserved-type randomize failed")
      finish_item(it);
    end
  endtask
endclass

// A malformed transmitter: payloads on packets that should not have them,
// and missing payloads on Data Packets. Relaxes c_payload_only_dp on
// purpose -- see the note above section 16.2.
class malformed_tx_seq extends uvm_sequence #(usb3_pkt_item);
  `uvm_object_utils(malformed_tx_seq)
  function new(string name = "malformed_tx_seq"); super.new(name); endfunction

  task body();
    repeat (500) begin
      usb3_pkt_item it = usb3_pkt_item::type_id::create("it");
      start_item(it);
      it.c_payload_only_dp.constraint_mode(0);
      if (!it.randomize() with { pkt_valid == 1; hdr_crc_ok == 1; })
        `uvm_error("RAND", "malformed randomize failed")
      finish_item(it);
    end
  endtask
endclass