Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
#
# This file is part of LiteX.
#
# Copyright (c) 2026 Florent Kermarrec <florent@enjoy-digital.fr>
# SPDX-License-Identifier: BSD-2-Clause
import unittest
from migen import *
from litex.gen import *
from litex.soc.interconnect import csr_bus, stream
from litex.soc.cores.uart import (
UART,
UARTCrossover,
UARTPads,
RS232PHY,
RS232PHYRX,
get_uart_core,
get_uart_supported_names,
)
class _LoopbackDUT(LiteXModule):
"""A single RS232PHY with `pads.rx` tied back to `pads.tx` for self-loopback tests."""
def __init__(self, clk_freq, baudrate):
self.pads = UARTPads()
self.phy = RS232PHY(self.pads, clk_freq=clk_freq, baudrate=baudrate)
self.comb += self.pads.rx.eq(self.pads.tx)
class _ErrorPHY(LiteXModule):
def __init__(self):
self.sink = stream.Endpoint([("data", 8)])
self.source = stream.Endpoint([("data", 8)])
self.rx_framing_error = Signal()
self.rx_overflow = Signal()
class TestUART(unittest.TestCase):
def test_receive_error_status_is_optional(self):
dut = UART(RS232PHY(UARTPads(), 1_000_000))
self.assertFalse(hasattr(dut, "_rx_errors"))
with self.assertRaisesRegex(ValueError, "PHY"):
UART(with_error_status=True)
def test_receive_error_csr_bank_access(self):
baseline = UART(_ErrorPHY())
baseline_names = [csr.name for csr in baseline.get_csrs()]
for data_width in [8, 32]:
with self.subTest(data_width=data_width):
class DUT(LiteXModule):
def __init__(self):
self.uart = UART(_ErrorPHY(), with_error_status=True)
self.bus = csr_bus.Interface(data_width=data_width)
self.csrs = self.uart.get_csrs()
self.bank = csr_bus.CSRBank(self.csrs, bus=self.bus)
dut = DUT()
self.assertEqual([csr.name for csr in dut.csrs], baseline_names + ["rx_errors"])
address = next(n for n, csr in enumerate(dut.bank.simple_csrs) if csr.name == "rx_errors")
def read():
yield dut.bus.adr.eq(address)
yield dut.bus.re.eq(1)
yield
yield
result = (yield dut.bus.dat_r)
yield dut.bus.re.eq(0)
return result
def gen():
yield dut.uart.phy.rx_framing_error.eq(1)
yield dut.uart.phy.rx_overflow.eq(1)
yield
yield dut.uart.phy.rx_framing_error.eq(0)
yield dut.uart.phy.rx_overflow.eq(0)
self.assertEqual((yield from read()), 3)
for mask, expected in [(1, 2), (0, 2), (2, 0)]:
yield dut.bus.adr.eq(address)
yield dut.bus.dat_w.eq(mask)
yield dut.bus.we.eq(1)
yield
yield dut.bus.we.eq(0)
for _ in range(4):
yield
self.assertEqual((yield from read()), expected)
run_simulation(dut, gen())
def test_receive_errors_from_serial_phy(self):
pads = UARTPads()
dut = UART(RS232PHY(pads, clk_freq=1_000_000, baudrate=62_500),
rx_fifo_depth=1, with_error_status=True)
def drive(level, cycles):
yield pads.rx.eq(level)
for _ in range(cycles):
yield
def send(value, stop=1):
yield from drive(0, 16)
for bit in range(8):
yield from drive((value >> bit) & 1, 16)
yield from drive(stop, 16)
yield from drive(1, 32)
def gen():
yield from drive(1, 32)
yield from send(0x12)
self.assertEqual((yield dut._rx_errors.fields.overflow), 0)
# Do not drain the RX FIFO: subsequent valid frames must report actual loss.
for value in [0x34, 0x56, 0x78]:
yield from send(value)
self.assertEqual((yield dut._rx_errors.fields.overflow), 1)
self.assertEqual((yield dut._rx_errors.fields.framing), 0)
yield from send(0xa5, stop=0)
self.assertEqual((yield dut._rx_errors.fields.framing), 1)
yield dut._rx_errors.wr_data.eq(1)
yield dut._rx_errors.wr_stb.eq(1)
yield
yield dut._rx_errors.wr_stb.eq(0)
yield
self.assertEqual((yield dut._rx_errors.fields.framing), 0)
self.assertEqual((yield dut._rx_errors.fields.overflow), 1)
run_simulation(dut, gen())
def test_receive_error_latching_and_cdc(self):
for phy_cd, period in [("sys", 10), ("phy", 7), ("phy", 29)]:
with self.subTest(phy_cd=phy_cd, period=period):
phy = _ErrorPHY()
dut = UART(phy, phy_cd=phy_cd, with_error_status=True)
fired = Signal()
cleared = Signal()
def errors():
yield phy.rx_framing_error.eq(1)
yield
yield phy.rx_framing_error.eq(0)
yield phy.rx_overflow.eq(1)
yield
yield phy.rx_overflow.eq(0)
yield fired.eq(1)
while not (yield cleared):
yield
def check():
while not (yield fired):
yield
for _ in range(20):
yield
self.assertEqual((yield dut._rx_errors.fields.framing), 1)
self.assertEqual((yield dut._rx_errors.fields.overflow), 1)
for mask, expected in [(0, (1, 1)), (1, (0, 1)), (2, (0, 0))]:
yield dut._rx_errors.wr_data.eq(mask)
yield dut._rx_errors.wr_stb.eq(1)
yield
yield dut._rx_errors.wr_stb.eq(0)
for _ in range(30):
yield
self.assertEqual(((yield dut._rx_errors.fields.framing),
(yield dut._rx_errors.fields.overflow)), expected)
yield cleared.eq(1)
generators = {"sys": [check()]}
generators.setdefault(phy_cd, []).append(errors())
run_simulation(dut, generators, clocks={"sys": 10, "phy": period})
def test_new_receive_error_wins_over_clear(self):
dut = UART(_ErrorPHY(), with_error_status=True)
# Inject the event at the PHY/UART boundary to hit the exact clear cycle.
def gen():
yield dut.phy.rx_framing_error.eq(1)
yield dut._rx_errors.wr_data.eq(1)
yield dut._rx_errors.wr_stb.eq(1)
yield
yield dut._rx_errors.wr_stb.eq(0)
yield dut.phy.rx_framing_error.eq(0)
yield
self.assertEqual((yield dut._rx_errors.fields.framing), 1)
run_simulation(dut, gen())
def test_rx_rejects_short_start_glitches(self):
for glitch_length in [1, 2, 4]:
with self.subTest(glitch_length=glitch_length):
pads = UARTPads()
dut = RS232PHYRX(pads, tuning_word=2**32//16)
received = []
@passive
def monitor():
while True:
if (yield dut.source.valid):
received.append((yield dut.source.data))
yield
def drive(level, cycles):
yield pads.rx.eq(level)
for _ in range(cycles):
yield
def gen():
yield dut.source.ready.eq(1)
yield from drive(1, 20)
yield from drive(0, glitch_length)
yield from drive(1, 24)
# A real frame soon after the glitch must not be missed.
value = 0xa5
yield from drive(0, 16)
for bit in range(8):
yield from drive((value >> bit) & 1, 16)
yield from drive(1, 48)
self.assertEqual(received, [value])
run_simulation(dut, [gen(), monitor()])
def test_supported_uart_names_include_soc_modes(self):
self.assertIn("crossover", get_uart_supported_names())
self.assertIn("crossover+uartbone", get_uart_supported_names())
self.assertIn("jtag_uart", get_uart_supported_names())
self.assertIn("sim", get_uart_supported_names())
self.assertIn("stub", get_uart_supported_names())
self.assertIn("stream", get_uart_supported_names())
self.assertIn("uartbone", get_uart_supported_names())
self.assertIn("usb_acm", get_uart_supported_names())
def test_get_uart_core_builds_crossover(self):
uart = get_uart_core("crossover", fifo_depth=8, rx_fifo_rx_we=True)
self.assertIsInstance(uart, UARTCrossover)
def test_get_uart_core_builds_regular_uart(self):
uart = get_uart_core("serial", uart_pads=UARTPads(), clk_freq=1_000_000)
self.assertIsInstance(uart, UART)
self.assertTrue(hasattr(uart, "phy"))
def test_get_uart_core_builds_stub_uart(self):
uart = get_uart_core("stub")
self.assertIsInstance(uart, UART)
self.assertFalse(hasattr(uart, "phy"))
def test_get_uart_core_returns_none_for_uartbone(self):
self.assertIsNone(get_uart_core("uartbone"))
def test_get_uart_core_validates_soc_supplied_dependencies(self):
with self.assertRaisesRegex(ValueError, "platform"):
get_uart_core("jtag_uart")
with self.assertRaisesRegex(ValueError, "pads"):
get_uart_core("sim")
with self.assertRaisesRegex(ValueError, "pads"):
get_uart_core("serial")
with self.assertRaisesRegex(ValueError, "clk_freq"):
get_uart_core("serial", uart_pads=UARTPads())
def test_loopback(self):
# Use a short "symbol time" so the test runs in tens of ms, not seconds.
# clk/baud = 10 → 10 sys cycles per UART bit, 100 cycles per 10-bit frame.
dut = _LoopbackDUT(clk_freq=1_000_000, baudrate=100_000)
payload = [0x12, 0x34, 0xAB, 0xCD, 0xA5, 0x5A, 0xFF, 0x00]
received = []
def tx_driver(dut):
for byte in payload:
yield dut.phy.sink.data.eq(byte)
yield dut.phy.sink.valid.eq(1)
yield
while not (yield dut.phy.sink.ready):
yield
yield dut.phy.sink.valid.eq(0)
yield
def rx_driver(dut):
yield dut.phy.source.ready.eq(1)
timeout = 0
while len(received) < len(payload):
if (yield dut.phy.source.valid) and (yield dut.phy.source.ready):
received.append((yield dut.phy.source.data))
yield
timeout += 1
self.assertLess(timeout, 20_000, "RX stalled")
run_simulation(dut, [tx_driver(dut), rx_driver(dut)])
self.assertEqual(received, payload)
def test_idle_line_no_spurious_rx(self):
# With `tx` tied to `rx` and no data ever sent, the RX path must stay idle.
dut = _LoopbackDUT(clk_freq=1_000_000, baudrate=100_000)
def gen(dut):
yield dut.phy.source.ready.eq(1)
for _ in range(2_000):
yield
self.assertEqual((yield dut.phy.source.valid), 0)
run_simulation(dut, gen(dut))
def test_long_burst_stable(self):
# A 16-byte burst exercises the TX backpressure path: the producer holds
# `sink.valid=1` for each byte and waits for `sink.ready` to pulse, which only happens
# when the TX FSM finishes its current 10-bit frame. Any reordering or drop would
# show up as a mismatch.
dut = _LoopbackDUT(clk_freq=1_000_000, baudrate=100_000)
payload = list(range(0x40, 0x40 + 16))
received = []
def tx_driver(dut):
for byte in payload:
yield dut.phy.sink.data.eq(byte)
yield dut.phy.sink.valid.eq(1)
yield
while not (yield dut.phy.sink.ready):
yield
yield dut.phy.sink.valid.eq(0)
yield
def rx_driver(dut):
yield dut.phy.source.ready.eq(1)
timeout = 0
while len(received) < len(payload):
if (yield dut.phy.source.valid) and (yield dut.phy.source.ready):
received.append((yield dut.phy.source.data))
yield
timeout += 1
self.assertLess(timeout, 100_000, "long burst stalled")
run_simulation(dut, [tx_driver(dut), rx_driver(dut)])
self.assertEqual(received, payload)
if __name__ == "__main__":
unittest.main()
22023cc43This file is pinned to the selected release. Download the original to open it in your design tool.