DOCSEARCHbyAlgolia
Submit Docs

LiteScope

repository·master·Indexed 42 days ago

https://github.com/enjoy-digital/litescope

A small-footprint, highly configurable embedded logic analyzer core for FPGAs, powered by Migen and LiteX. It supports RLE compression, subsampling, and various bridge interfaces including UART, Ethernet, and PCIe. It can be used as a LiteX library or integrated into design flows via generated Verilog RTL.

Tokens
845
Snippets
2
Records
4
Agent score
3%

What's inside LiteScope

  1. Configure LiteScopeAnalyzer with Run-Length Encoding (RLE)

    master

    LiteScopeAnalyzer supports optional Run-Length Encoding (RLE) to compress repeated samples in Block RAM.

    Hardware Configuration (Migen): When defining the analyzer in your hardware description, set with_rle=True and specify an rle_length (e.g., 256).

    Software Configuration (Python Driver): If RLE was enabled at build time, you must explicitly enable it in the driver before performing a capture using configure_rle(True).

    Important Note on Depth: When RLE is enabled, the depth and capture length parameters refer to the number of encoded storage words, not the final count of decoded logical samples. A compressed capture can result in more logical samples than the configured storage length.

    # Hardware side configuration
analyzer = LiteScopeAnalyzer(
    signals,
    depth      = 1024,
    with_rle   = True,
    rle_length = 256,
)

# Software side driver configuration
from litescope import LiteScopeAnalyzerDriver

analyzer = LiteScopeAnalyzerDriver(bus.regs, "analyzer", config_csv="analyzer.csv")
# Enable RLE for the capture
analyzer.configure_rle(True)

# To cap the decoded logical samples returned by the driver:
data = analyzer.upload(max_samples=1024)

  2. Get started with LiteScope

    master

    To use LiteScope, follow these setup steps:

    1. Install Python 3.6+ and your specific FPGA vendor's development tools.
    2. Install LiteX and its associated cores by following the LiteX installation guide.
    3. For integration examples, refer to the LiteX-Boards repository or the examples directory within this repository.

    LiteScope can be used as a LiteX library or integrated into standard design flows by generating Verilog RTL.

  3. Run LiteScope tests

    master

    Unit and simulation tests are located in the ./test/ directory. You can run the full suite or individual tests using pytest.

    To run all tests:

    python3 -m pytest -q

    To run a specific test file:

    python3 -m pytest -q test/test_driver.py
    $ python3 -m pytest -q

  4. Use litescope_cli for signal capture

    master

    The litescope_cli tool uses the CSV file generated by LiteScopeAnalyzer to manage signal groups and capture parameters.

    Key CLI Flags:

    • --group N: Selects a specific capture group. Groups are defined on the SoC side (e.g., {0: signals_a, 1: signals_b}). Use --list --group=N to see available signals in a group.
    • --subsampling N: Keeps one sample every N scope clock cycles. 1 is no subsampling. The effective sample rate becomes samplerate / N.
    • --offset: Sets the number of pre-trigger samples to keep. The scope_trig marker is placed at this index.
    • --length: The number of stored samples/words to read.
      • If omitted, the driver reads the full analyzer depth.
      • Note: If RLE is enabled, this value refers to the encoded storage-word count, not the decoded logical sample count.