test_phy_abstractions.py

"""Tests for multi-vendor PHY abstractions (Phases 10a–10d).

Covers all 12 improvement proposals:
  A1: PCIePHY base class
  A2: LTSSM width
  A3: Shared channel
  B1: 256-bit support
  B2: Endianness
  C1: PCIeConfig
  C2: Signal types
  D1: Credits
  E1: BAR decode
  F1: MSI interface
  G1: PCIeResource
  H1: Config access
"""

import unittest

from amaranth import *
from amaranth.hdl import Shape
from amaranth.lib.data import StructLayout
from amaranth.sim import Simulator as Simulator

from amaranth_pcie.common import (
    phy_layout, phy_signature, get_bar_mask, MB,
)
from amaranth_pcie.phy.common import (
    PCIePHY,
    PCIeConfig,
    PCIeCreditInterface,
    PCIeMSIInterface,
    PCIeConfigAccess,
    PCIeResource,
    LTSSMTracer,
    ltssm_state_names,
)
from amaranth_pcie.phy.sim import SimPCIePHY
from amaranth_pcie.phy.s7pciephy import S7PCIEPHY
from amaranth_pcie.tlp.depacketizer import TLPDepacketizer
from amaranth_pcie.tlp.packetizer import TLPPacketizer
from amaranth_pcie.tlp.common import dword_endianness_swap
from amaranth_pcie.core.msi import PCIeMSI


# =====================================================================
# A1: PCIePHY Base Class
# =====================================================================

class TestPCIePHYBaseClass(unittest.TestCase):
    """A1: Test the PCIePHY abstract base class."""

    def test_sim_phy_is_instance_of_pcie_phy(self):
        """SimPCIePHY inherits from PCIePHY."""
        phy = SimPCIePHY(data_width=64)
        self.assertIsInstance(phy, PCIePHY)

    def test_s7_phy_is_instance_of_pcie_phy(self):
        """S7PCIEPHY inherits from PCIePHY."""
        phy = S7PCIEPHY(nlanes=1, data_width=64)
        self.assertIsInstance(phy, PCIePHY)

    def test_has_bar_hit_default_false(self):
        """has_bar_hit() returns False by default (no bar_hit attribute)."""
        phy = SimPCIePHY(data_width=64)
        self.assertFalse(phy.has_bar_hit())

    def test_has_credits_default_false(self):
        """has_credits() returns False by default (no credits attribute)."""
        phy = SimPCIePHY(data_width=64)
        self.assertFalse(phy.has_credits())

    def test_has_config_access_default_false(self):
        """has_config_access() returns False by default."""
        phy = SimPCIePHY(data_width=64)
        self.assertFalse(phy.has_config_access())

    def test_bar0_mask_property(self):
        """bar0_mask is computed from bar0_size."""
        phy = SimPCIePHY(data_width=64, bar0_size=1 * MB)
        expected_mask = get_bar_mask(1 * MB)
        self.assertEqual(phy.bar0_mask, expected_mask)

    def test_bar0_mask_property_s7(self):
        """bar0_mask is computed from bar0_size for S7PCIEPHY."""
        phy = S7PCIEPHY(nlanes=1, data_width=64, bar0_size=1 * MB)
        expected_mask = get_bar_mask(1 * MB)
        self.assertEqual(phy.bar0_mask, expected_mask)

    def test_ltssm_state_names_property(self):
        """ltssm_state_names property returns the state name dict."""
        phy = SimPCIePHY(data_width=64)
        names = phy.ltssm_state_names
        self.assertIsInstance(names, dict)
        self.assertEqual(names[0x10], "L0")
        self.assertEqual(names[0x00], "Detect.Quiet")

    def test_has_bar_hit_true_when_set(self):
        """has_bar_hit() returns True when bar_hit attribute exists."""
        phy = SimPCIePHY(data_width=64)
        phy.bar_hit = Signal(6)
        self.assertTrue(phy.has_bar_hit())

    def test_has_credits_true_when_set(self):
        """has_credits() returns True when credits is a PCIeCreditInterface."""
        phy = SimPCIePHY(data_width=64)
        phy.credits = PCIeCreditInterface()
        self.assertTrue(phy.has_credits())

    def test_has_config_access_true_when_set(self):
        """has_config_access() returns True when config_access is set."""
        phy = SimPCIePHY(data_width=64)
        phy.config_access = PCIeConfigAccess()
        self.assertTrue(phy.has_config_access())


# =====================================================================
# A2: LTSSM Width
# =====================================================================

class TestLTSSMWidth(unittest.TestCase):
    """A2: Test LTSSMTracer with different widths."""

    def test_ltssm_tracer_default_width(self):
        """LTSSMTracer default width is 6."""
        tracer = LTSSMTracer()
        self.assertEqual(tracer._ltssm_width, 6)
        self.assertEqual(Shape.cast(tracer.history_new.shape()).width, 6)
        self.assertEqual(Shape.cast(tracer.history_old.shape()).width, 6)

    def test_ltssm_tracer_width_5(self):
        """LTSSMTracer with width=5."""
        tracer = LTSSMTracer(ltssm_width=5)
        self.assertEqual(tracer._ltssm_width, 5)
        self.assertEqual(Shape.cast(tracer.history_new.shape()).width, 5)
        self.assertEqual(Shape.cast(tracer.history_old.shape()).width, 5)

    def test_ltssm_tracer_width_8(self):
        """LTSSMTracer with width=8."""
        tracer = LTSSMTracer(ltssm_width=8)
        self.assertEqual(tracer._ltssm_width, 8)
        self.assertEqual(Shape.cast(tracer.history_new.shape()).width, 8)
        self.assertEqual(Shape.cast(tracer.history_old.shape()).width, 8)

    def test_ltssm_tracer_with_external_signal(self):
        """LTSSMTracer accepts an external LTSSM signal."""
        ltssm_sig = Signal(6)
        tracer = LTSSMTracer(ltssm=ltssm_sig)
        self.assertIs(tracer._ltssm, ltssm_sig)

    def test_ltssm_state_names_dict(self):
        """ltssm_state_names has expected entries."""
        self.assertIn(0x00, ltssm_state_names)
        self.assertIn(0x10, ltssm_state_names)
        self.assertIn(0x24, ltssm_state_names)
        self.assertEqual(ltssm_state_names[0x10], "L0")
        self.assertEqual(ltssm_state_names[0x24], "HotReset")


# =====================================================================
# A3: Shared Channel
# =====================================================================

class TestSharedChannel(unittest.TestCase):
    """A3: Test shared_channel attribute."""

    def test_sim_phy_shared_channel_false(self):
        """SimPCIePHY.shared_channel is False."""
        phy = SimPCIePHY(data_width=64)
        self.assertFalse(phy.shared_channel)

    def test_s7_phy_shared_channel_true(self):
        """S7PCIEPHY.shared_channel is True."""
        phy = S7PCIEPHY(nlanes=1, data_width=64)
        self.assertTrue(phy.shared_channel)

    def test_base_class_shared_channel_default(self):
        """PCIePHY base class default shared_channel is False."""
        self.assertFalse(PCIePHY.shared_channel)


# =====================================================================
# B1: 256-bit Support
# =====================================================================

class Test256BitSupport(unittest.TestCase):
    """B1: Test 256-bit data width support."""

    def test_phy_signature_256(self):
        """phy_signature(256) creates correct layout."""
        sig = phy_signature(256)
        iface = sig.create()
        # Check dat width
        dat_shape = Shape.cast(iface.payload.dat.shape())
        self.assertEqual(dat_shape.width, 256)
        # Check be width
        be_shape = Shape.cast(iface.payload.be.shape())
        self.assertEqual(be_shape.width, 32)  # 256 // 8

    def test_phy_layout_256(self):
        """phy_layout(256) has correct field widths."""
        layout = phy_layout(256)
        fields = {name: Shape.cast(field.shape).width for name, field in layout}
        self.assertEqual(fields["dat"], 256)
        self.assertEqual(fields["be"], 32)

    def test_sim_phy_256(self):
        """SimPCIePHY(data_width=256) constructs successfully."""
        phy = SimPCIePHY(data_width=256)
        self.assertEqual(phy.data_width, 256)
        self.assertIsInstance(phy, PCIePHY)

    def test_sim_phy_128(self):
        """SimPCIePHY(data_width=128) constructs successfully."""
        phy = SimPCIePHY(data_width=128)
        self.assertEqual(phy.data_width, 128)

    def test_sim_phy_invalid_width(self):
        """SimPCIePHY rejects invalid data widths."""
        with self.assertRaises(AssertionError):
            SimPCIePHY(data_width=32)
        with self.assertRaises(AssertionError):
            SimPCIePHY(data_width=512)

    def test_depacketizer_256(self):
        """TLPDepacketizer(data_width=256) constructs successfully."""
        depkt = TLPDepacketizer(data_width=256, endianness="big")
        self.assertEqual(depkt._data_width, 256)

    def test_packetizer_256(self):
        """TLPPacketizer(data_width=256) constructs successfully."""
        pkt = TLPPacketizer(data_width=256, endianness="big")
        self.assertEqual(pkt._data_width, 256)


# =====================================================================
# B2: Endianness
# =====================================================================

class TestEndianness(unittest.TestCase):
    """B2: Test endianness support including 'native' mode."""

    def test_native_endianness_passthrough(self):
        """dword_endianness_swap with 'native' returns pass-through assignments."""
        src = Signal(64)
        dst = Signal(64)
        stmts = dword_endianness_swap(src, dst, 64, "native", mode="dat")
        # Should produce 2 assignments (2 DWORDs), each a pass-through
        self.assertEqual(len(stmts), 2)

    def test_big_endianness_swap(self):
        """dword_endianness_swap with 'big' produces swap assignments."""
        src = Signal(64)
        dst = Signal(64)
        stmts = dword_endianness_swap(src, dst, 64, "big", mode="dat")
        self.assertEqual(len(stmts), 2)

    def test_little_endianness_passthrough(self):
        """dword_endianness_swap with 'little' returns pass-through."""
        src = Signal(64)
        dst = Signal(64)
        stmts = dword_endianness_swap(src, dst, 64, "little", mode="dat")
        self.assertEqual(len(stmts), 2)

    def test_invalid_endianness_raises(self):
        """dword_endianness_swap rejects invalid endianness."""
        src = Signal(64)
        dst = Signal(64)
        with self.assertRaises(ValueError):
            dword_endianness_swap(src, dst, 64, "middle", mode="dat")

    def test_depacketizer_accepts_native(self):
        """TLPDepacketizer accepts 'native' endianness."""
        depkt = TLPDepacketizer(data_width=64, endianness="native")
        self.assertEqual(depkt._endianness, "native")

    def test_packetizer_accepts_native(self):
        """TLPPacketizer accepts 'native' endianness."""
        pkt = TLPPacketizer(data_width=64, endianness="native")
        self.assertEqual(pkt._endianness, "native")

    def test_be_swap_native(self):
        """dword_endianness_swap with 'native' in 'be' mode."""
        src = Signal(8)
        dst = Signal(8)
        stmts = dword_endianness_swap(src, dst, 64, "native", mode="be")
        self.assertEqual(len(stmts), 2)

    def test_be_swap_big(self):
        """dword_endianness_swap with 'big' in 'be' mode."""
        src = Signal(8)
        dst = Signal(8)
        stmts = dword_endianness_swap(src, dst, 64, "big", mode="be")
        self.assertEqual(len(stmts), 2)

    def test_256bit_endianness_swap(self):
        """dword_endianness_swap works with 256-bit data."""
        src = Signal(256)
        dst = Signal(256)
        stmts = dword_endianness_swap(src, dst, 256, "big", mode="dat")
        self.assertEqual(len(stmts), 8)  # 256 / 32 = 8 DWORDs


# =====================================================================
# C1: PCIeConfig
# =====================================================================

class TestPCIeConfig(unittest.TestCase):
    """C1: Test PCIeConfig standardized config interface."""

    def test_config_has_all_fields(self):
        """PCIeConfig has all required fields."""
        cfg = PCIeConfig()
        self.assertTrue(hasattr(cfg, "bus_number"))
        self.assertTrue(hasattr(cfg, "device_number"))
        self.assertTrue(hasattr(cfg, "function_number"))
        self.assertTrue(hasattr(cfg, "max_payload_size"))
        self.assertTrue(hasattr(cfg, "max_request_size"))
        self.assertTrue(hasattr(cfg, "command"))
        self.assertTrue(hasattr(cfg, "status"))

    def test_config_field_widths(self):
        """PCIeConfig fields have correct widths."""
        cfg = PCIeConfig()
        self.assertEqual(Shape.cast(cfg.bus_number.shape()).width, 8)
        self.assertEqual(Shape.cast(cfg.device_number.shape()).width, 5)
        self.assertEqual(Shape.cast(cfg.function_number.shape()).width, 3)
        self.assertEqual(Shape.cast(cfg.max_payload_size.shape()).width, 16)
        self.assertEqual(Shape.cast(cfg.max_request_size.shape()).width, 16)
        self.assertEqual(Shape.cast(cfg.command.shape()).width, 16)
        self.assertEqual(Shape.cast(cfg.status.shape()).width, 16)

    def test_config_id_property(self):
        """PCIeConfig.id composes BDF correctly."""
        cfg = PCIeConfig()
        id_sig = cfg.id
        # id = Cat(function_number, device_number, bus_number)
        # Total width: 3 + 5 + 8 = 16 bits
        self.assertEqual(Shape.cast(id_sig.shape()).width, 16)

    def test_sim_phy_config_is_pcie_config(self):
        """SimPCIePHY.config is a PCIeConfig instance."""
        phy = SimPCIePHY(data_width=64)
        self.assertIsInstance(phy.config, PCIeConfig)

    def test_s7_phy_config_is_pcie_config(self):
        """S7PCIEPHY.config is a PCIeConfig instance."""
        phy = S7PCIEPHY(nlanes=1, data_width=64)
        self.assertIsInstance(phy.config, PCIeConfig)

    def test_config_id_width(self):
        """PCIeConfig.id has 16-bit width (bus + device + function)."""
        cfg = PCIeConfig()
        id_sig = cfg.id
        # id = Cat(function_number[2:0], device_number[4:0], bus_number[7:0])
        # Total width: 3 + 5 + 8 = 16 bits
        self.assertEqual(Shape.cast(id_sig.shape()).width, 16)


# =====================================================================
# C2: Signal Types
# =====================================================================

class TestSignalTypes(unittest.TestCase):
    """C2: Test that config values are Signals, and _bytes are ints."""

    def test_sim_phy_max_request_size_is_signal(self):
        """SimPCIePHY.config.max_request_size is a Signal."""
        phy = SimPCIePHY(data_width=64)
        self.assertIsInstance(phy.config.max_request_size, Signal)

    def test_sim_phy_max_payload_size_is_signal(self):
        """SimPCIePHY.config.max_payload_size is a Signal."""
        phy = SimPCIePHY(data_width=64)
        self.assertIsInstance(phy.config.max_payload_size, Signal)

    def test_sim_phy_max_request_size_bytes_is_int(self):
        """SimPCIePHY.max_request_size_bytes is a Python int."""
        phy = SimPCIePHY(data_width=64, max_request_size=512)
        self.assertIsInstance(phy.max_request_size_bytes, int)
        self.assertEqual(phy.max_request_size_bytes, 512)

    def test_sim_phy_max_payload_size_bytes_is_int(self):
        """SimPCIePHY.max_payload_size_bytes is a Python int."""
        phy = SimPCIePHY(data_width=64, max_payload_size=128)
        self.assertIsInstance(phy.max_payload_size_bytes, int)
        self.assertEqual(phy.max_payload_size_bytes, 128)

    def test_s7_phy_max_request_size_bytes_is_int(self):
        """S7PCIEPHY.max_request_size_bytes is a Python int."""
        phy = S7PCIEPHY(nlanes=1, data_width=64)
        self.assertIsInstance(phy.max_request_size_bytes, int)
        self.assertEqual(phy.max_request_size_bytes, 512)

    def test_s7_phy_max_payload_size_bytes_is_int(self):
        """S7PCIEPHY.max_payload_size_bytes is a Python int."""
        phy = S7PCIEPHY(nlanes=1, data_width=64)
        self.assertIsInstance(phy.max_payload_size_bytes, int)
        self.assertEqual(phy.max_payload_size_bytes, 512)

    def test_legacy_max_request_size_delegates_to_config(self):
        """PCIePHY.max_request_size property delegates to config."""
        phy = SimPCIePHY(data_width=64)
        # The property should return the config Signal
        self.assertIs(phy.max_request_size, phy.config.max_request_size)

    def test_legacy_max_payload_size_delegates_to_config(self):
        """PCIePHY.max_payload_size property delegates to config."""
        phy = SimPCIePHY(data_width=64)
        self.assertIs(phy.max_payload_size, phy.config.max_payload_size)

    def test_legacy_id_delegates_to_config(self):
        """PCIePHY.id property delegates to config.id."""
        phy = SimPCIePHY(data_width=64)
        # Both should return the same Cat expression
        phy_id = phy.id
        cfg_id = phy.config.id
        # They should be equivalent Cat expressions
        self.assertEqual(Shape.cast(phy_id.shape()).width, 16)
        self.assertEqual(Shape.cast(cfg_id.shape()).width, 16)


# =====================================================================
# D1: Credits
# =====================================================================

class TestPCIeCreditInterface(unittest.TestCase):
    """D1: Test PCIeCreditInterface."""

    def test_basic_credit_interface(self):
        """PCIeCreditInterface has all required availability signals."""
        cred = PCIeCreditInterface()
        self.assertTrue(hasattr(cred, "posted_header_available"))
        self.assertTrue(hasattr(cred, "posted_data_available"))
        self.assertTrue(hasattr(cred, "non_posted_header_available"))
        self.assertTrue(hasattr(cred, "non_posted_data_available"))
        self.assertTrue(hasattr(cred, "completion_header_available"))
        self.assertTrue(hasattr(cred, "completion_data_available"))

    def test_basic_no_count_signals(self):
        """Basic mode does not have count signals."""
        cred = PCIeCreditInterface(extended=False)
        self.assertFalse(hasattr(cred, "posted_header_count"))
        self.assertFalse(hasattr(cred, "posted_data_count"))

    def test_extended_credit_interface(self):
        """Extended mode has count signals."""
        cred = PCIeCreditInterface(extended=True)
        self.assertTrue(hasattr(cred, "posted_header_count"))
        self.assertTrue(hasattr(cred, "posted_data_count"))
        self.assertTrue(hasattr(cred, "non_posted_header_count"))
        self.assertTrue(hasattr(cred, "non_posted_data_count"))
        self.assertTrue(hasattr(cred, "completion_header_count"))
        self.assertTrue(hasattr(cred, "completion_data_count"))

    def test_extended_count_widths(self):
        """Extended count signals have correct widths."""
        cred = PCIeCreditInterface(extended=True)
        self.assertEqual(Shape.cast(cred.posted_header_count.shape()).width, 8)
        self.assertEqual(Shape.cast(cred.posted_data_count.shape()).width, 12)
        self.assertEqual(Shape.cast(cred.non_posted_header_count.shape()).width, 8)
        self.assertEqual(Shape.cast(cred.non_posted_data_count.shape()).width, 12)
        self.assertEqual(Shape.cast(cred.completion_header_count.shape()).width, 8)
        self.assertEqual(Shape.cast(cred.completion_data_count.shape()).width, 12)

    def test_sim_phy_has_credits_false(self):
        """SimPCIePHY.has_credits() returns False (no credits by default)."""
        phy = SimPCIePHY(data_width=64)
        self.assertFalse(phy.has_credits())

    def test_availability_signals_are_signals(self):
        """Availability signals are Amaranth Signals."""
        cred = PCIeCreditInterface()
        self.assertIsInstance(cred.posted_header_available, Signal)
        self.assertIsInstance(cred.posted_data_available, Signal)
        self.assertIsInstance(cred.non_posted_header_available, Signal)
        self.assertIsInstance(cred.non_posted_data_available, Signal)
        self.assertIsInstance(cred.completion_header_available, Signal)
        self.assertIsInstance(cred.completion_data_available, Signal)


# =====================================================================
# E1: BAR Decode
# =====================================================================

class TestBARDecode(unittest.TestCase):
    """E1: Test BAR hit passthrough in phy_signature."""

    def test_phy_signature_with_bar_hit(self):
        """phy_signature(64, with_bar_hit=True) includes bar_hit field."""
        sig = phy_signature(64, with_bar_hit=True)
        iface = sig.create()
        self.assertTrue(hasattr(iface.payload, "bar_hit"))
        bar_hit_shape = Shape.cast(iface.payload.bar_hit.shape())
        self.assertEqual(bar_hit_shape.width, 6)

    def test_phy_signature_without_bar_hit(self):
        """phy_signature(64, with_bar_hit=False) does not include bar_hit."""
        sig = phy_signature(64, with_bar_hit=False)
        iface = sig.create()
        self.assertFalse(hasattr(iface.payload, "bar_hit"))

    def test_phy_signature_default_no_bar_hit(self):
        """phy_signature(64) defaults to no bar_hit."""
        sig = phy_signature(64)
        iface = sig.create()
        self.assertFalse(hasattr(iface.payload, "bar_hit"))

    def test_phy_layout_with_bar_hit(self):
        """phy_layout(64, with_bar_hit=True) includes bar_hit."""
        layout = phy_layout(64, with_bar_hit=True)
        fields = {name: Shape.cast(field.shape).width for name, field in layout}
        self.assertIn("bar_hit", fields)
        self.assertEqual(fields["bar_hit"], 6)

    def test_phy_layout_without_bar_hit(self):
        """phy_layout(64, with_bar_hit=False) does not include bar_hit."""
        layout = phy_layout(64, with_bar_hit=False)
        fields = {name: Shape.cast(field.shape).width for name, field in layout}
        self.assertNotIn("bar_hit", fields)


# =====================================================================
# F1: MSI Interface
# =====================================================================

class TestPCIeMSIInterface(unittest.TestCase):
    """F1: Test PCIeMSIInterface basic and extended modes."""

    def test_basic_msi_interface(self):
        """PCIeMSIInterface(extended=False) has basic signals."""
        msi = PCIeMSIInterface(extended=False)
        self.assertTrue(hasattr(msi, "valid"))
        self.assertTrue(hasattr(msi, "ready"))
        self.assertTrue(hasattr(msi, "dat"))
        self.assertIsInstance(msi.valid, Signal)
        self.assertIsInstance(msi.ready, Signal)
        self.assertIsInstance(msi.dat, Signal)
        self.assertEqual(Shape.cast(msi.dat.shape()).width, 8)

    def test_basic_no_extended_signals(self):
        """Basic mode does not have extended signals."""
        msi = PCIeMSIInterface(extended=False)
        self.assertFalse(hasattr(msi, "ack"))
        self.assertFalse(hasattr(msi, "status"))
        self.assertFalse(hasattr(msi, "msinum"))

    def test_extended_msi_interface(self):
        """PCIeMSIInterface(extended=True) has extended signals."""
        msi = PCIeMSIInterface(extended=True)
        # Basic signals
        self.assertTrue(hasattr(msi, "valid"))
        self.assertTrue(hasattr(msi, "ready"))
        self.assertTrue(hasattr(msi, "dat"))
        # Extended signals
        self.assertTrue(hasattr(msi, "ack"))
        self.assertTrue(hasattr(msi, "status"))
        self.assertTrue(hasattr(msi, "msinum"))
        self.assertIsInstance(msi.ack, Signal)
        self.assertIsInstance(msi.status, Signal)
        self.assertIsInstance(msi.msinum, Signal)

    def test_extended_signal_widths(self):
        """Extended signals have correct widths."""
        msi = PCIeMSIInterface(extended=True)
        self.assertEqual(Shape.cast(msi.status.shape()).width, 3)
        self.assertEqual(Shape.cast(msi.msinum.shape()).width, 5)

    def test_extended_flag(self):
        """extended attribute is stored correctly."""
        msi_basic = PCIeMSIInterface(extended=False)
        msi_ext = PCIeMSIInterface(extended=True)
        self.assertFalse(msi_basic.extended)
        self.assertTrue(msi_ext.extended)

    def test_pcie_msi_with_extended_interface(self):
        """PCIeMSI accepts a PCIeMSIInterface with extended=True."""
        phy_msi = PCIeMSIInterface(extended=True)
        msi = PCIeMSI(width=32, phy_msi=phy_msi)
        self.assertEqual(msi.width, 32)

    def test_pcie_msi_without_phy_msi(self):
        """PCIeMSI works without phy_msi parameter."""
        msi = PCIeMSI(width=16)
        self.assertEqual(msi.width, 16)


# =====================================================================
# G1: PCIeResource
# =====================================================================

class TestPCIeResource(unittest.TestCase):
    """G1: Test PCIeResource board resource descriptor."""

    def test_basic_construction(self):
        """PCIeResource constructs with required parameters."""
        res = PCIeResource(0, lanes=4, refclk_freq=100e6)
        self.assertEqual(res.number, 0)
        self.assertEqual(res.lanes, 4)
        self.assertEqual(res.refclk_freq, 100e6)

    def test_optional_parameters(self):
        """PCIeResource stores optional parameters."""
        res = PCIeResource(
            1,
            lanes=8,
            refclk_freq=100e6,
            refclk="some_clk",
            perst="some_rst",
            wake="some_wake",
        )
        self.assertEqual(res.number, 1)
        self.assertEqual(res.lanes, 8)
        self.assertEqual(res.refclk, "some_clk")
        self.assertEqual(res.perst, "some_rst")
        self.assertEqual(res.wake, "some_wake")

    def test_extras_dict(self):
        """PCIeResource stores extras dict."""
        res = PCIeResource(
            0, lanes=1, refclk_freq=100e6,
            extras={"vendor": "xilinx", "speed": "gen2"},
        )
        self.assertEqual(res.extras["vendor"], "xilinx")
        self.assertEqual(res.extras["speed"], "gen2")

    def test_extras_default_empty(self):
        """PCIeResource extras defaults to empty dict."""
        res = PCIeResource(0, lanes=1, refclk_freq=100e6)
        self.assertEqual(res.extras, {})

    def test_defaults_none(self):
        """PCIeResource optional params default to None."""
        res = PCIeResource(0, lanes=1, refclk_freq=100e6)
        self.assertIsNone(res.refclk)
        self.assertIsNone(res.perst)
        self.assertIsNone(res.wake)

    def test_various_lane_counts(self):
        """PCIeResource accepts various lane counts."""
        for lanes in [1, 2, 4, 8, 16]:
            res = PCIeResource(0, lanes=lanes, refclk_freq=100e6)
            self.assertEqual(res.lanes, lanes)


# =====================================================================
# H1: Config Access
# =====================================================================

class TestPCIeConfigAccess(unittest.TestCase):
    """H1: Test PCIeConfigAccess interface."""

    def test_has_read_signals(self):
        """PCIeConfigAccess has all read port signals."""
        ca = PCIeConfigAccess()
        self.assertTrue(hasattr(ca, "read_en"))
        self.assertTrue(hasattr(ca, "read_addr"))
        self.assertTrue(hasattr(ca, "read_data"))
        self.assertTrue(hasattr(ca, "read_valid"))

    def test_has_write_signals(self):
        """PCIeConfigAccess has all write port signals."""
        ca = PCIeConfigAccess()
        self.assertTrue(hasattr(ca, "write_en"))
        self.assertTrue(hasattr(ca, "write_addr"))
        self.assertTrue(hasattr(ca, "write_data"))
        self.assertTrue(hasattr(ca, "write_be"))
        self.assertTrue(hasattr(ca, "write_done"))

    def test_signal_widths(self):
        """PCIeConfigAccess signals have correct widths."""
        ca = PCIeConfigAccess()
        self.assertEqual(Shape.cast(ca.read_addr.shape()).width, 12)
        self.assertEqual(Shape.cast(ca.read_data.shape()).width, 32)
        self.assertEqual(Shape.cast(ca.write_addr.shape()).width, 12)
        self.assertEqual(Shape.cast(ca.write_data.shape()).width, 32)
        self.assertEqual(Shape.cast(ca.write_be.shape()).width, 4)

    def test_all_signals_are_signals(self):
        """All PCIeConfigAccess attributes are Amaranth Signals."""
        ca = PCIeConfigAccess()
        for attr_name in ["read_en", "read_addr", "read_data", "read_valid",
                          "write_en", "write_addr", "write_data", "write_be",
                          "write_done"]:
            self.assertIsInstance(getattr(ca, attr_name), Signal,
                                 f"{attr_name} should be a Signal")


# =====================================================================
# Integration: Elaboration smoke tests
# =====================================================================

def _elaborate_check(elaboratable):
    """Helper: verify an Elaboratable can be elaborated via Simulator."""
    sim = Simulator(elaboratable)
    sim.run()


class TestElaborationSmoke(unittest.TestCase):
    """Smoke tests: verify key modules elaborate without errors."""

    def test_ltssm_tracer_elaborates(self):
        """LTSSMTracer elaborates successfully."""
        tracer = LTSSMTracer(ltssm_width=6)
        _elaborate_check(tracer)

    def test_sim_phy_elaborates(self):
        """SimPCIePHY elaborates successfully."""
        phy = SimPCIePHY(data_width=64)
        _elaborate_check(phy)

    def test_sim_phy_256_elaborates(self):
        """SimPCIePHY(data_width=256) elaborates successfully."""
        phy = SimPCIePHY(data_width=256)
        _elaborate_check(phy)

    def test_sim_phy_no_loopback_elaborates(self):
        """SimPCIePHY(with_loopback=False) elaborates successfully."""
        phy = SimPCIePHY(data_width=64, with_loopback=False)
        _elaborate_check(phy)

    def test_depacketizer_64_elaborates(self):
        """TLPDepacketizer(data_width=64) elaborates."""
        depkt = TLPDepacketizer(data_width=64, endianness="big")
        _elaborate_check(depkt)

    def test_depacketizer_128_elaborates(self):
        """TLPDepacketizer(data_width=128) elaborates."""
        depkt = TLPDepacketizer(data_width=128, endianness="big")
        _elaborate_check(depkt)

    def test_depacketizer_256_elaborates(self):
        """TLPDepacketizer(data_width=256) elaborates."""
        depkt = TLPDepacketizer(data_width=256, endianness="big")
        _elaborate_check(depkt)

    def test_depacketizer_native_elaborates(self):
        """TLPDepacketizer with 'native' endianness elaborates."""
        depkt = TLPDepacketizer(data_width=64, endianness="native")
        _elaborate_check(depkt)

    def test_packetizer_64_elaborates(self):
        """TLPPacketizer(data_width=64) elaborates."""
        pkt = TLPPacketizer(data_width=64, endianness="big")
        _elaborate_check(pkt)

    def test_packetizer_128_elaborates(self):
        """TLPPacketizer(data_width=128) elaborates."""
        pkt = TLPPacketizer(data_width=128, endianness="big")
        _elaborate_check(pkt)

    def test_packetizer_256_elaborates(self):
        """TLPPacketizer(data_width=256) elaborates."""
        pkt = TLPPacketizer(data_width=256, endianness="big")
        _elaborate_check(pkt)

    def test_packetizer_native_elaborates(self):
        """TLPPacketizer with 'native' endianness elaborates."""
        pkt = TLPPacketizer(data_width=64, endianness="native")
        _elaborate_check(pkt)


if __name__ == "__main__":
    unittest.main()