generate_pinout module#

Generate the XCVP1002 component module from an AMD package pinout file.

Usage (from the repository root, any Python 3.12+, stdlib only):

python -m jitxexamples.jumpstart_kits.js1_stackup_components.versal_fpga.tools.generate_pinout <pinout.txt> [--out FILE] [--report] [--check]

Input: The AMD ASCII package pinout file for the VP1002 in NFVI1369 (xcvp1002nfvi1369pkg.txt), downloaded by the user from AMD’s “Versal Adaptive SoC Package Device Pinout Files” page. The file is proprietary to AMD and is never committed — keep it in the git-ignored .context/ directory. Only the factual pin name/position data it describes is embedded in the generated Python module, with provenance.
Output: xcvp1002.py next to this package’s other modules: a declarative jitx.Component with one Port per ball (indexed lists for repeated rail names), zero-indexed ball coordinates, GTM quad groupings, the XPIO pins of each DDRMC triplet with the file’s DDRMC column, and symbol partitions. Deterministic: same input file -> byte-identical output (--check re-generates and diffs against the committed file).
Doctrine: No string-keyed runtime models and no getattr in the emitted code: every pin reference in the generated module is an explicit attribute expression. Ball references (“AB34”) exist only here, at generation time, where they are converted to (row, col) grid coordinates.

ROW_LOOKUP = 'ABCDEFGHJKLMNPRTUVWY'#: BGA row letters in order; I, O, Q, S, X, Z are skipped (JEDEC/AMD style).

MAX_PINS_PER_BOX = 64#: Pins per box when chunking large rails into symbol boxes. Restates symbols.MAX_PINS_PER_BOX because this tool is deliberately stdlib-only (it must run without a jitx environment); the owner enforces the cap at instantiation (SymbolPartition.__post_init__) and the test suite asserts the two values stay equal.

XPIO_TRIPLET_RE = re.compile('_N(\\d)P(\\d)_M(\\d+)P(\\d+)_(\\d{3})$')#

nibble and pin in the bank, then triplet and pin in the triplet (..._N4P0_M0P132_702). AM013 “SelectIO Pin Definitions”.

Type:: XPIO pin name tail

TRIPLET_BANKS = 3#: XPIO banks per DDRMC triplet, nibbles per bank, pins per nibble.

BANK_NIBBLES = 9#: XPIO banks per DDRMC triplet, nibbles per bank, pins per nibble.

NIBBLE_PINS = 6#: XPIO banks per DDRMC triplet, nibbles per bank, pins per nibble.

DDRMC_VALUES = ('YES', 'YES_PLUS_GC', 'NO')#: Values of the pin file’s “DDRMC Only” column, AM013 “About ASCII Package Files” (X5IO’s NO_NMU_SHARED does not occur on XPIO pins).

class PinEntry(ball, name, bank, io_type, slr, perf, ddrmc, row, col)[source]#

Bases: object

One data row of the pinout file.

Parameters:

ball (str)
name (str)
bank (str)
io_type (str)
slr (str)
perf (str)
ddrmc (str)
row (int)
col (int)

ball: str#

name: str#

bank: str#

io_type: str#

slr: str#

perf: str#

ddrmc: str#

row: int#

col: int#

class Pinout(source_name, sha256, provenance, entries, total_from_footer, num_rows, num_cols)[source]#

Bases: object

Parsed pinout file plus its own provenance lines.

Parameters:

source_name (str)
sha256 (str)
provenance (tuple[str, ...])
entries (tuple[PinEntry, ...])
total_from_footer (int)
num_rows (int)
num_cols (int)

source_name: str#

sha256: str#

provenance: tuple[str, ...]#

entries: tuple[PinEntry, ...]#

total_from_footer: int#

num_rows: int#

num_cols: int#

ball_to_rc(ball)[source]#

"AB34" -> (21, 33) — zero-indexed (row, col) grid coordinates.

Return type:: tuple[int, int]
Parameters:: ball (str)

rc_to_ball(row, col)[source]#

Inverse of ball_to_rc(), for round-trip self-checks.

Return type:

str

Parameters:

row (int)
col (int)

parse_pinout(text, source_name)[source]#

Parse the AMD ASCII pinout file; fail loudly on any surprise.

Return type:

Pinout

Parameters:

text (str)
source_name (str)

natural_key(name)[source]#

Sort key treating digit runs numerically (L2 before L10).

Return type:: tuple
Parameters:: name (str)

class PinModel(pinout, rails, uniques)[source]#

Bases: object

Classified pinout: repeated rail names vs unique pin names.

Parameters:

pinout (Pinout)
rails (dict[str, tuple[PinEntry, ...]])
uniques (dict[str, PinEntry])

pinout: Pinout#

rails: dict[str, tuple[PinEntry, ...]]#

uniques: dict[str, PinEntry]#

classify(pinout)[source]#

Return type:: PinModel
Parameters:: pinout (Pinout)

class GTMQuadGroup(bank, rxp, rxn, txp, txn, refclkp, refclkn)[source]#

Bases: object

Lane/refclk pin names of one GTM bank, index-ordered.

Parameters:

bank (int)
rxp (tuple[str, ...])
rxn (tuple[str, ...])
txp (tuple[str, ...])
txn (tuple[str, ...])
refclkp (tuple[str, ...])
refclkn (tuple[str, ...])

bank: int#

rxp: tuple[str, ...]#

rxn: tuple[str, ...]#

txp: tuple[str, ...]#

txn: tuple[str, ...]#

refclkp: tuple[str, ...]#

refclkn: tuple[str, ...]#

gtm_quads(model)[source]#

Extract GTM quads from the unique-pin roster; validate completeness.

Return type:: tuple[GTMQuadGroup, ...]
Parameters:: model (PinModel)

xpio_triplets(model)[source]#

XPIO pins of each DDRMC triplet, indexed by pin-in-triplet (MxP).

Validates that every triplet is three consecutive banks of nine six-pin nibbles, that each name’s nibble and pin agree with its MxP index, and that the DDRMC column holds a value AM013 defines.

Return type:: dict[int, tuple[PinEntry, ...]]
Parameters:: model (PinModel)

class Partition(comment, left, right, down=())[source]#

Bases: object

One symbol box, expressed as emission strings.

Parameters:

comment (str)
left (tuple[str, ...])
right (tuple[str, ...])
down (tuple[str, ...])

comment: str#

left: tuple[str, ...]#

right: tuple[str, ...]#

down: tuple[str, ...] = ()#

partition_symbols(model)[source]#

Symbol partition policy: banks first, then rails packed into boxes.

Return type:: list[Partition]
Parameters:: model (PinModel)

emit_module(model)[source]#

Return type:: str
Parameters:: model (PinModel)

inventory_report(model)[source]#

Return type:: str
Parameters:: model (PinModel)

main(argv=None)[source]#

Return type:: int
Parameters:: argv (list[str] | None)