Source code for jitxexamples.jumpstart_kits.vp1002_lpddr4.package_delays

"""Synthetic package delays for the VP1002's LPDDR4 pins: estimates, not AMD
data.

AMD publishes a Versal device's per-pin package delays through Vivado's
I/O ports CSV export (File > Export > Export I/O Ports). UG899 v2022.2,
Appendix A, describes its columns: "I/O Bank" and "Pin Number" for every
pin in the device, "Site" and "Site Type", and "Min/Max Trace Delay (ps)",
the delay from the die's pad site to the package ball. UG863 v1.12,
"Required Memory Routing Guidelines for All Interfaces", says to include
package delay in routing constraints and to use the midpoint where a minimum
and a maximum are given.

The VP1002's own values were not available for this kit, so
:py:data:`SYNTHETIC_CSV` holds estimates in the shape of that export, for the
XPIO pins of triplet M0 (banks 700, 701 and 702). Each estimate is a stated
formula on the ball's real position (:py:func:`estimate`); none is a measured
or AMD-published value. The two legs of an XPIO P/N pair (pins ``2k`` and
``2k + 1`` of a nibble) take the mean of their two estimates, on the
assumption that a package matches a pair's legs; how closely AMD matches
them is not known here. The file has the export's bank, pin and delay
columns only, with the two delay columns named ``Min Trace Delay (ps)`` and
``Max Trace Delay (ps)``; check those names against your own export, and
replace the file with it before relying on any delay that includes it.

The file is generated. To regenerate it, or to check it against the formula::

    python -m jitxexamples.jumpstart_kits.vp1002_lpddr4.package_delays [--check]
"""

from __future__ import annotations

import argparse
import sys
import unittest
from collections.abc import Sequence
from math import hypot, sqrt
from pathlib import Path

from jitx.substrate import SubstrateContext
from jitx.test import TestCase

from jitxexamples.substrates.reference_18layer import Reference18Substrate

from ..js1_stackup_components.versal_fpga.tools.generate_pinout import rc_to_ball
from ..js1_stackup_components.versal_fpga.xcvp1002 import XCVP1002

SYNTHETIC_CSV = Path(__file__).with_name("package_delays_synthetic.csv")
"The generated file: one row per XPIO pin of triplet M0."

PITCH_MM = 0.92
"NFVI1369 ball pitch, from the package's mechanical drawing (JS1's landpattern)."

CENTER = 18
"Grid index of the middle row and column of the 37 by 37 ball array."

ASSUMED_DK = 3.3
"Assumed relative permittivity of the package substrate's build-up dielectric."

ROUTING_FACTOR = 1.4
"Assumed ratio of a package trace's routed length to the straight-line distance."

VERTICAL_PS = 8.0
"Assumed delay through the package's vertical interconnect, bump to ball, in ps."

SPREAD = 0.03
"Assumed fractional spread of the minimum and maximum about the estimate."

C_MM_PER_PS = 0.299792458
"Speed of light in mm per ps."

COLUMNS = ("I/O Bank", "Pin Number", "Min Trace Delay (ps)", "Max Trace Delay (ps)")
"""The columns, named after UG899 Appendix A. A real export carries more
columns and a row for every pin; read it by column name."""

HEADER = (
    "# SYNTHETIC ESTIMATES, NOT AMD DATA. Generated by",
    "# jitxexamples.jumpstart_kits.vp1002_lpddr4.package_delays from ball position:",
    "# mid = VERTICAL_PS + distance from package centre * ROUTING_FACTOR * sqrt(ASSUMED_DK) / c;",
    "# min and max = mid -/+ SPREAD * mid; both legs of a P/N pair take the pair's mean.",
    "# Replace with your Vivado export",
    "# (Export I/O Ports, CSV) for the real per-pin package delays.",
)


[docs] def estimate(row: int, col: int) -> tuple[float, float]: """Synthetic minimum and maximum package delay in ps for the ball at a zero-indexed grid position: a trace from the package centre, which this estimate takes as the die's position, plus the vertical path.""" distance = PITCH_MM * hypot(row - CENTER, col - CENTER) mid = VERTICAL_PS + distance * ROUTING_FACTOR * sqrt(ASSUMED_DK) / C_MM_PER_PS return round(mid * (1 - SPREAD), 1), round(mid * (1 + SPREAD), 1)
[docs] def triplet_balls(fpga: XCVP1002) -> list[tuple[int, str, tuple[int, int]]]: """Bank, ball and grid position of each XPIO pin of triplet M0, in pin order. Call where JITX instantiation is active (in a circuit or a :py:class:`jitx.test.TestCase`).""" position = {id(port): rc for port, rc in fpga.ball_assignments()} found: list[tuple[int, str, tuple[int, int]]] = [] for index, pin in enumerate(fpga.xpio_triplet_pins()[0]): rc = position[id(pin.port)] found.append((700 + index // 54, rc_to_ball(*rc), rc)) return found
[docs] def render(balls: Sequence[tuple[int, str, tuple[int, int]]]) -> str: """The CSV text for these pins, given in triplet pin order so that pins ``2k`` and ``2k + 1`` are a P/N pair.""" lines = [*HEADER, ",".join(COLUMNS)] for index, (bank, ball, rc) in enumerate(balls): pair = (estimate(*rc), estimate(*balls[index ^ 1][2])) low = round((pair[0][0] + pair[1][0]) / 2, 1) high = round((pair[0][1] + pair[1][1]) / 2, 1) lines.append(f"{bank},{ball},{low:.1f},{high:.1f}") return "\n".join(lines) + "\n"
class _Generate(TestCase): """Runs :py:func:`triplet_balls` where instantiation is active.""" text = "" def test_render(self) -> None: # The land pattern needs a substrate; the balls do not depend on which. with SubstrateContext(Reference18Substrate()): type(self).text = render(triplet_balls(XCVP1002()))
[docs] def generated() -> str: """The CSV text the formula gives for the current component.""" result = unittest.TextTestRunner(stream=sys.stderr, verbosity=0).run( unittest.defaultTestLoader.loadTestsFromTestCase(_Generate) ) if not result.wasSuccessful(): raise RuntimeError("could not instantiate the VP1002 to read its balls") return _Generate.text
[docs] def main(argv: list[str] | None = None) -> int: ap = argparse.ArgumentParser(description="Write or check SYNTHETIC_CSV.") ap.add_argument("--check", action="store_true", help="exit 1 if the file differs") args = ap.parse_args(argv) text = generated() if args.check: current = SYNTHETIC_CSV.read_text(encoding="utf-8") if current != text: print(f"{SYNTHETIC_CSV} differs from the formula; regenerate it") return 1 print(f"{SYNTHETIC_CSV} matches") return 0 SYNTHETIC_CSV.write_text(text, encoding="utf-8") print(f"wrote {SYNTHETIC_CSV}") return 0
if __name__ == "__main__": sys.exit(main())