.. _utilities_prbs:

================
PRBS Utilities
================

For link validation with deterministic pseudo-random traffic, Rogue provides a
PRBS family with both tree-managed ``pyrogue.utilities.prbs`` wrappers and the
direct ``rogue.utilities.Prbs`` endpoint for smaller script-only tests.

PRBS implementations also exist in FPGA and VHDL designs, so Rogue PRBS
endpoints are commonly used to send traffic into firmware checkers or to verify
traffic generated by firmware sources.

How PRBS Fits In A Stream Graph
===============================

Rogue PRBS support is implemented as stream endpoints, so it can be inserted
directly into existing stream topologies for test and validation:

- Generator role:
  emits deterministic frames into a transport or processing path.
- Checker role:
  receives frames and reports mismatch/error counters.
- Combined loopback role:
  connects TX and RX paths end-to-end to verify full data flow.

Because patterns are deterministic, PRBS tests are useful both for first
bring-up and for recurring regression checks where repeatability matters.

Direct Endpoints And Tree-Managed Devices
=========================================

Two Python forms are common:

- ``rogue.utilities.Prbs``:
  lightweight direct stream endpoint for scripts and non-tree tests.
- ``pyrogue.utilities.prbs`` wrappers (``PrbsTx``, ``PrbsRx``, ``PrbsPair``):
  tree-managed integration with Variables/Commands for GUI and runtime control.

Common controls/counters exposed by the implementation include width/taps
selection, transmit period, payload generation/check enable, and frame/error
counters.

``PrbsPair`` is a convenience wrapper that keeps both transmit and receive
control under one node for loopback tests and end-to-end validation.

The direct Rogue endpoint is the simpler fit when a test script just needs to
generate or check traffic inside a stream graph. The PyRogue wrappers are the
better fit when operators, GUIs, or client code need tree-visible counters and
controls.

Typical Validation Workflow
===========================

1. Generate PRBS frames at the source side.
2. Route traffic through the transport/path under test.
3. Check receive counters and error counters at the sink side.
4. Tune width/taps/period when matching target link characteristics.

C++ API details for PRBS utilities are documented in
:doc:`/api/cpp/utilities/prbs/index`.

Typical patterns are:

- Generate PRBS frames and capture them to file.
- Replay file data into a PRBS checker.
- Use the PyRogue ``PrbsTx``/``PrbsRx`` wrappers for GUI-visible control and
  counters.
- Use ``PrbsPair`` when one tree node should own both directions of a software
  loopback or end-to-end smoke test.
- Validate software-to-firmware and firmware-to-software PRBS links during FPGA
  bring-up.

Logging
=======

The core ``rogue.utilities.Prbs`` implementation uses Rogue C++ logging with
two static logger names:

- ``pyrogue.prbs.tx``
- ``pyrogue.prbs.rx``

Enable them before constructing the PRBS object:

.. code-block:: python

   import rogue
   import rogue.utilities as ru

   rogue.Logging.setFilter('pyrogue.prbs', rogue.Logging.Debug)
   prbs = ru.Prbs()

The PyRogue wrappers also have their own Python loggers, but the transport/data
path debug output from the underlying PRBS generator/checker comes from the
C++ logger names above.

Subtopics
=========

- :doc:`writing`
  Starts from ``pyrogue.utilities.prbs.PrbsTx``, then shows the matching direct
  ``rogue.utilities.Prbs`` transmit form.
- :doc:`reading`
  Starts from ``pyrogue.utilities.prbs.PrbsRx`` and ``PrbsPair``, then shows
  the matching direct ``rogue.utilities.Prbs`` receive form.

API Reference
=============

- Python:

  - :doc:`/api/python/rogue/utilities/prbs/prbs`
  - :doc:`/api/python/pyrogue/utilities/prbs/prbstx`
  - :doc:`/api/python/pyrogue/utilities/prbs/prbsrx`
  - :doc:`/api/python/pyrogue/utilities/prbs/prbspair`

- C++:

  - :doc:`/api/cpp/utilities/prbs/prbs`

Related Topics
==============

- File capture/replay integration:
  :doc:`/built_in_modules/utilities/fileio/index`
- Stream graph wiring patterns:
  :doc:`/stream_interface/connecting`
- Top-level PyRogue tree devices:
  :doc:`/pyrogue_tree/builtin_devices/index`

.. toctree::
   :maxdepth: 1
   :caption: PRBS Utilities:

   writing
   reading