Source code for jitxexamples.jumpstart_kits.vp1002_lpddr4.pinout

"""The LPDDR4 x32 pinout the VP1002 offers on banks 702 and 701, as data.

Positions are triplet-relative: ``Pos(bank, nibble, pin)``, where ``bank`` is
0, 1 or 2 within the triplet, ``nibble`` is N0 to N8 and ``pin`` is P0 to P5.
``Pos.index`` is the ``MxP`` number in the pin file's pin names. On the
VP1002 the only triplet is M0, banks 700, 701 and 702.

The layout is the single channel x32 pinout, flipped, on the third and second
banks of the triplet. Its free choices are AMD's two LPDDR4/4X pin swaps:
a byte may take either byte slot of its channel, with its DQS and DMI, and a
byte's eight DQ may take its slot's DQ pins in any order. Command, address,
clock, chip select, clock enable, reset and system clock pins are fixed.
That is ``2 * 2 * factorial(8) ** 4`` assignments,
:py:func:`assignment_count`.

Sources
-------

- AMD PG313, *Versal Adaptive SoC Programmable Network on Chip and
  Integrated Memory Controller LogiCORE IP Product Guide*, v1.1, 2026-06-23,
  "LPDDR4/4X Pin Rules" (the swaps, Tables 1 and 2) and "Single Channel
  LPDDR4/4X Interfaces" (the nibble use).
- AMD Vivado-Design-Tutorials, tag 2025.2,
  ``Versal/PCB_Design/Memory_Pinouts/README.md``, Appendix B (the flipped
  pinout).
- PG313 places most fixed pins only to the nibble. The pin within each
  nibble is where channel 0 of AMD's VMK180, VCK190 and VPK120 boards puts it
  (XilinxBoardStore tag 2025.2; VCK190 from Vivado-Design-Tutorials tag
  2025.2, ``lpddr4_mc3_vck190.xdc``). VCK190 is single rank and has no CS1.
- The offer has one CKE per channel, as every one of those boards maps it,
  including the dual-rank VMK180 and VPK120; a design nets it to both of the
  memory channel's CKE balls. UG863's LPDDR4/4x timing table lists CKE0 and
  CKE1 per channel for dual-rank devices, so a design that needs a second
  CKE does not use this layout as is.

PG313 says every pin swap must be captured in the design's XDC and validated
before generating hardware. This module exports no XDC and does not claim
Vivado legality: validating the chosen assignment is the designer's step.
"""

from __future__ import annotations

from collections.abc import Mapping
from dataclasses import dataclass
from enum import Enum
from math import factorial

BANK_NIBBLES = 9
NIBBLE_PINS = 6


[docs] @dataclass(frozen=True, order=True) class Pos: """A triplet-relative pin position.""" bank: int "0, 1 or 2 within the triplet" nibble: int "0 to 8" pin: int "0 to 5" @property def index(self) -> int: """The ``MxP`` number of this position in the pin file.""" return (self.bank * BANK_NIBBLES + self.nibble) * NIBBLE_PINS + self.pin
[docs] class Channel(Enum): """An LPDDR4 x16 channel of the memory.""" A = "A" B = "B"
[docs] @dataclass(frozen=True) class ByteSlot: """The nibble pair one byte occupies: DQS_T and DQS_C on P0 and P1 of one nibble, DMI on P0 of its partner, the eight DQ on P2 to P5 of both.""" channel: Channel bank: int dqs_nibble: int @property def dmi_nibble(self) -> int: """The partner nibble, with DMI on P0.""" return self.dqs_nibble ^ 1 @property def dqs_t(self) -> Pos: return Pos(self.bank, self.dqs_nibble, 0) @property def dqs_c(self) -> Pos: return Pos(self.bank, self.dqs_nibble, 1) @property def dmi(self) -> Pos: return Pos(self.bank, self.dmi_nibble, 0) @property def dq(self) -> tuple[Pos, ...]: """The eight DQ positions: P2 to P5 of the DQS nibble, then of the DMI nibble. A byte's DQ may take them in any order.""" return tuple( Pos(self.bank, n, p) for n in (self.dqs_nibble, self.dmi_nibble) for p in range(2, NIBBLE_PINS) )
[docs] @dataclass(frozen=True) class PinLayout: """A layout at pin level: the fixed pins and the byte slots.""" slots: tuple[ByteSlot, ...] "Byte slots; slot ``k`` holds byte ``k`` before any byte swap" fixed: Mapping[str, Pos]
[docs] def byte_orders(self) -> list[tuple[int, int, int, int]]: """Every allowed byte-to-slot assignment: entry ``k`` is the slot index byte ``k`` takes. A byte stays in its own channel.""" a = [i for i, s in enumerate(self.slots) if s.channel is Channel.A] b = [i for i, s in enumerate(self.slots) if s.channel is Channel.B] return [ (a0, a1, b0, b1) for a0, a1 in (tuple(a), tuple(reversed(a))) for b0, b1 in (tuple(b), tuple(reversed(b))) ]
A, B = Channel.A, Channel.B LPDDR4_X32 = PinLayout( slots=( ByteSlot(A, 1, 3), # byte 0: bank 701, DQS on N3 ByteSlot(A, 2, 5), # byte 1: bank 702, DQS on N5 ByteSlot(B, 1, 7), # byte 2: bank 701, DQS on N7 ByteSlot(B, 2, 6), # byte 3: bank 702, DQS on N6 ), fixed={ # Bank 702 N0 and N1: channel A command, address and clock "CA2_A": Pos(2, 0, 0), "CS1_A": Pos(2, 0, 1), "CA1_A": Pos(2, 0, 2), "CA0_A": Pos(2, 0, 3), "CS0_A": Pos(2, 0, 4), "CA3_A": Pos(2, 0, 5), "CK_T_A": Pos(2, 1, 0), "CK_C_A": Pos(2, 1, 1), "CA4_A": Pos(2, 1, 2), "CA5_A": Pos(2, 1, 3), "CKE_A": Pos(2, 1, 4), # Bank 702 N2 and N3: channel B command, address and clock "CA0_B": Pos(2, 2, 2), "CA3_B": Pos(2, 2, 4), "CA2_B": Pos(2, 2, 5), "CK_T_B": Pos(2, 3, 0), "CK_C_B": Pos(2, 3, 1), "CA5_B": Pos(2, 3, 2), "CA4_B": Pos(2, 3, 3), "CKE_B": Pos(2, 3, 4), "CA1_B": Pos(2, 3, 5), # P1 of two DMI nibbles "CS0_B": Pos(2, 7, 1), "CS1_B": Pos(2, 4, 1), # Bank 702 N8: system clock and reset "SYS_CLK_P": Pos(2, 8, 0), "SYS_CLK_N": Pos(2, 8, 1), "RESET_N": Pos(2, 8, 2), }, ) """The offered layout: single channel x32, flipped, on banks 702 and 701."""
[docs] def assignment_count(layout: PinLayout = LPDDR4_X32) -> int: """Number of distinct pin assignments the layout allows.""" return len(layout.byte_orders()) * factorial(8) ** len(layout.slots)