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, 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.

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#
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, ...]#
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:
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]#
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, ...]#
gtm_quads(model)[source]#

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

Return type:

tuple[GTMQuadGroup, ...]

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, ...] = ()#
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)