DOCSEARCHbyAlgolia
Submit Docs

SLAC Ultimate RTL Framework (SURF)

repository·main·Indexed 19 days ago

https://github.com/slaclab/surf

A comprehensive RTL library providing foundational, protocol-specific, and vendor-specific hardware components for FPGA and ASIC design. It includes an AXI-family library (Lite, Stream, AXI4), base RTL components for CDC, FIFOs, and RAM, DSP support blocks, and a wide array of Ethernet cores including MAC, IPv4, UDP, and RoCEv2. The framework also provides vendor-specific device support for manufacturers such as Xilinx, TI, and Micron, and includes tools for building conda packages.

Tokens
9.1K
Snippets
10
Records
29
Agent score
67%

What's inside SURF

  1. Overview of the AXI library structure

    main

    The axi/ directory contains reusable AXI-family RTL (Register Transfer Level) components and wrappers. To integrate the submodules used by SURF builds, use the top-level axi/ruckus.tcl script.

    The library is organized into the following functional areas:

    • axi-lite/: AXI-Lite records, crossbars, endpoints, masters, slaves, monitors, and IP-integrator adapters.
    • axi-stream/: AXI Stream records, FIFOs, muxes, monitors, protocol adapters, and stream wrappers.
    • axi4/: Full AXI4 support blocks and adapters.
    • bridge/: Bridges between AXI-family buses and SURF protocol records.
    • dma/: DMA register, descriptor, FIFO, and stream integration cores.
    • simlink/: Simulator-link support and C/C++/VHDL components used by simulation flows.

  2. Overview of SURF repository structure

    main

    The SURF (SLAC Ultimate RTL Framework) repository is organized into several functional domains for RTL development and verification:

    • AXI: Implementation of AXI-Lite, AXI4, AXI Stream, DMA, bridges, and simulation-link RTL.
    • Base: Foundational RTL helpers including CDC (Clock Domain Crossing), FIFO, RAM, reset, delay, and CRC.
    • Devices: Vendor and component-specific RTL support.
    • DSP: Generic and Xilinx-specific Digital Signal Processing support.
    • Ethernet: High-speed Ethernet cores including MAC, raw Ethernet, IPv4, UDP, and RoCEv2.
    • Protocols: Protocol cores such as PGP, SSI, SRP, RSSI, CoaXPress, JESD204B, and peripheral buses.
    • Xilinx: Wrappers for Xilinx-family primitives and XVC UDP support.
    • Python: The PyRogue package layout located under python/surf.
    • Tests: Regression testing infrastructure using cocotb, including methodology and simulator conventions.

  3. Overview of the Ethernet module in SURF

    main

    The Ethernet module provides a collection of cores for Ethernet MAC, framing, IP/UDP, RoCEv2, and high-speed Ethernet implementations. It is organized into common logic cores and speed/PHY-specific cores.

    Core Components

    • MAC & Framing: EthMacCore/ provides common Ethernet MAC logic, while RawEthFramer/ provides support for raw Ethernet frame transmit and receive.
    • Speed & PHY Specific Cores: Includes GigEthCore/, TenGigEthCore/, XauiCore/, XlauiCore/, and Caui4Core/ for specific speed and PHY-family requirements.
    • Network Protocols:
      • IpV4Engine/: Handles ARP, ICMP, IGMP, IPv4 receive/transmit, and demux helpers.
      • UdpEngine/: Provides UDP protocol support.
      • RoCEv2/: Provides RDMA over Converged Ethernet v2 support.

  4. Overview of DSP support blocks in SURF

    main

    The dsp/ directory contains reusable signal-processing support blocks for hardware designs. The library is organized into two main subtrees based on portability and vendor specificity:

    • generic/: Contains portable DSP RTL designed to work across various FPGA families.
    • xilinx/: Contains Xilinx-specific DSP implementations and wrappers.

    Usage Recommendation: Always prefer generic/ implementations for your designs. Only use the xilinx/ subtree if your design specifically requires a vendor-specific primitive, a particular timing path, or a vendor IP wrapper. When using vendor-specific logic, ensure family-specific assumptions are isolated within the xilinx/ subtree and guarded by ruckus logic where appropriate.

  5. Overview of Xilinx-specific SURF components

    main

    The xilinx/ directory in SURF contains RTL wrappers, primitive integrations, and helper IP specifically designed for Xilinx hardware.

    Usage Best Practice: When working with higher-level RTL, you should use generic SURF wrappers whenever available instead of instantiating Xilinx primitives directly. This maintains hardware abstraction and portability.

  6. Overview of the RoCEv2 Engine Hardware Implementation

    main

    The ethernet/RoCEv2 directory contains Verilog files generated from Bluespec SystemVerilog (BSV) source code. This implementation provides a hardware-optimized RoCEv2 engine and an iCRC calculation engine.

    Key characteristics of this specific implementation:

    • Optimized for Resource Constraints: The receiving path and support for RDMA-Read operations have been removed to minimize hardware resource consumption, making it suitable for smaller FPGAs.
    • Fixed Resource Scaling: To maintain a lightweight footprint, the generated Verilog is hardcoded to support a specific set of resources:
      • 1 PD (Protection Domain)
      • 1 QP (Queue Pair)
      • 2 CQ (Completion Queues)
      • 2 MR (Memory Regions)

    Note: If you require different resource settings (e.g., more QPs or MRs), you cannot simply reconfigure these Verilog files; the core must be re-generated from the original or modified BSV source repositories.

  7. Understand the SURF Base RTL structure

    main

    The base/ directory contains the foundational Register Transfer Level (RTL) components used throughout the SURF repository. The entry point for loading these libraries is the top-level base/ruckus.tcl file.

    Instead of duplicating logic for Clock-Domain Crossing (CDC), FIFOs, RAM, resets, or CRC in higher-level subsystems, you should reuse these established base modules to ensure consistency and reliability.

  8. Understand the SURF protocol hierarchy and organization

    main

    The protocols/ directory contains reusable protocol cores layered on top of the base, AXI, and Ethernet libraries. Protocols are organized into functional categories:

    • Link/protocol families: Includes pgp/, ssi/, srp/, rssi/, sugoi/, salt/, glink/, htsp/, and coaxpress/.
    • Peripheral/control protocols: Includes i2c/, spi/, uart/, mdio/, pmbus/, and saci/.
    • Data formatting and protection helpers: Includes batcher/, packetizer/, line-codes/, hamming-ecc/, and event-frame-sequencer/.
    • JESD support: Located in jesd204b/.

  9. Explore the SURF Python package layout

    main

    The surf package is organized into functional sub-packages containing PyRogue models and register maps:

    • surf.axi: AXI register blocks, DMA, stream monitors, version blocks, and AXI support.
    • surf.devices: Vendor and component-specific PyRogue register maps.
    • surf.ethernet: Ethernet, MAC, UDP, RoCE, and high-speed Ethernet support models.
    • surf.protocols: Protocol-specific models (e.g., CoaXPress, PGP, RSSI, SSI).
    • surf.xilinx: Xilinx-specific register maps and helper devices.
    • surf.dsp: DSP-related support.
    • surf.misc: Miscellaneous small utilities.

  10. Understand the SURF device repository layout

    main

    The devices/ directory provides vendor and component-specific RTL support. It is organized by manufacturer and includes generic transceiver support.

    Directory Structure

    • Manufacturer Folders: (e.g., AnalogDevices/, Microchip/, Micron/, Silabs/, Ti/, Xilinx/) contain individual device cores.
    • Device Folders: Typically contain:
      • rtl/: Synthesizable register and control logic.
      • sim/: (Optional) Simulation models.
      • FPGA-family implementation directories: (Optional).
      • ruckus.tcl: Local configuration file.
    • transceivers/: Contains generic pluggable transceiver support, such as SFP/QSFP control and status blocks.

  11. Best practices for AXI component development

    main

    When contributing or adding new components to the AXI library, follow these structural guidelines:

    1. Use existing records: Always use existing package record types before adding flattened ports.
    2. Placement of adapters: Place durable adapter entities in ip_integrator/ or wrappers/.
    3. Testing: Keep executable cocotb tests located under tests/axi/.

  12. Protocol implementation requirements for RTL and Python models

    main

    When implementing or extending protocols in SURF, follow these structural and semantic guidelines:

    RTL Structure

    Many protocol folders separate portable logic (found in core/ or rtl/) from FPGA-family specific PHY wrappers.

    Semantic Preservation

    Ensure that protocol record types and sideband semantics are preserved. Key signals to maintain include:

    • TKEEP
    • TLAST
    • TUSER/SOF/EOFE
    • VC (Virtual Channel) fields
    • AXI-Lite status/control register maps

    Python Integration

    If the RTL exposes a register space visible to PyRogue, place the corresponding Python-facing register models under python/surf/protocols.