chipflow.packaging ================== .. py:module:: chipflow.packaging .. autoapi-nested-parse:: Package definitions and pin allocation. This module provides everything needed to define IC packages and allocate pins to component interfaces, including: - Pin dataclasses (PowerPins, JTAGPins, BringupPins) - Port description models (PortDesc, PortMap) - Lock file models (LockFile, Package) - Base classes (BasePackageDef, LinearAllocPackageDef) - Concrete package types (QuadPackageDef, BareDiePackageDef, GAPackageDef, OpenframePackageDef) - Pin allocation algorithms Submodules ---------- .. toctree:: :maxdepth: 1 /chipflow-lib/autoapi/chipflow/packaging/allocation/index /chipflow-lib/autoapi/chipflow/packaging/base/index /chipflow-lib/autoapi/chipflow/packaging/commands/index /chipflow-lib/autoapi/chipflow/packaging/grid_array/index /chipflow-lib/autoapi/chipflow/packaging/lockfile/index /chipflow-lib/autoapi/chipflow/packaging/openframe/index /chipflow-lib/autoapi/chipflow/packaging/pins/index /chipflow-lib/autoapi/chipflow/packaging/port_desc/index /chipflow-lib/autoapi/chipflow/packaging/standard/index /chipflow-lib/autoapi/chipflow/packaging/utils/index Exceptions ---------- .. autoapisummary:: chipflow.packaging.UnableToAllocate Classes ------- .. autoapisummary:: chipflow.packaging.PowerType chipflow.packaging.JTAGWire chipflow.packaging.PortType chipflow.packaging.PowerPins chipflow.packaging.JTAGPins chipflow.packaging.BringupPins chipflow.packaging.PortDesc chipflow.packaging.PortMap chipflow.packaging.Package chipflow.packaging.LockFile chipflow.packaging.BasePackageDef chipflow.packaging.LinearAllocPackageDef chipflow.packaging.BareDiePackageDef chipflow.packaging.QuadPackageDef chipflow.packaging.GAPin chipflow.packaging.GALayout chipflow.packaging.GAPackageDef chipflow.packaging.OFPin chipflow.packaging.OpenframePackageDef chipflow.packaging.PinCommand Functions --------- .. autoapisummary:: chipflow.packaging.load_pinlock chipflow.packaging.lock_pins Package Contents ---------------- .. py:class:: PowerType Bases: :py:obj:`enum.StrEnum` Type of power pin (power or ground) .. py:class:: JTAGWire Bases: :py:obj:`enum.StrEnum` Wire names in a JTAG interface .. py:class:: PortType Bases: :py:obj:`enum.StrEnum` Type of port .. py:class:: PowerPins Bases: :py:obj:`Generic`\ [\ :py:obj:`Pin`\ ] A matched pair of power pins, with optional notation of the voltage range. Attributes: power: The power (VDD) pin ground: The ground (VSS) pin voltage: Optional voltage range or specific voltage name: Optional name for this power domain .. py:method:: to_set() Convert power pins to a set .. py:class:: JTAGPins Bases: :py:obj:`Generic`\ [\ :py:obj:`Pin`\ ] Pins for a JTAG interface. Attributes: trst: Test Reset pin tck: Test Clock pin tms: Test Mode Select pin tdi: Test Data In pin tdo: Test Data Out pin .. py:method:: to_set() Convert JTAG pins to a set .. py:class:: BringupPins Bases: :py:obj:`Generic`\ [\ :py:obj:`Pin`\ ] Essential pins for bringing up an IC, always in fixed locations. These pins are used for initial testing and debug of the IC. Attributes: core_power: List of core power pin pairs core_clock: Core clock input pin core_reset: Core reset input pin core_heartbeat: Heartbeat output pin (for liveness testing) core_jtag: Optional JTAG interface pins .. py:method:: to_set() Convert all bringup pins to a set .. py:class:: PortDesc Bases: :py:obj:`pydantic.BaseModel`, :py:obj:`Generic`\ [\ :py:obj:`chipflow.packaging.pins.Pin`\ ] Description of a port and its pin assignment. Attributes: type: Type of port (e.g., 'io', 'clock', 'reset', 'power', 'heartbeat') pins: List of pins assigned to this port, or None if not yet allocated port_name: Name of the port iomodel: IO model configuration for this port .. py:property:: width Width of the port (number of pins) .. py:property:: direction Direction of the port .. py:property:: invert :type: collections.abc.Iterable[bool] | None Inversion settings for port wires .. py:class:: PortMap Bases: :py:obj:`pydantic.BaseModel` Mapping of components to interfaces to ports. This represents the complete pin allocation for an IC package, organized hierarchically by component and interface. .. py:method:: get_ports(component, interface) Get ports for a specific component and interface. Args: component: Component name interface: Interface name Returns: Dictionary of port names to PortDesc, or None if not found .. py:method:: get_clocks() Get all clock ports in the port map .. py:method:: get_resets() Get all reset ports in the port map .. py:class:: Package Bases: :py:obj:`pydantic.BaseModel` Serializable identifier for a defined packaging option. Attributes: package_type: Package type (discriminated union of all PackageDef types) .. py:class:: LockFile Bases: :py:obj:`pydantic.BaseModel` Representation of a pin lock file. The lock file stores the complete pin allocation for a design, allowing pins to remain consistent across design iterations. Attributes: process: Semiconductor process being used package: Information about the physical package port_map: Mapping of components to interfaces to ports metadata: Amaranth metadata, for reference .. py:class:: BasePackageDef Bases: :py:obj:`pydantic.BaseModel`, :py:obj:`Generic`\ [\ :py:obj:`PinType`\ ], :py:obj:`abc.ABC` Abstract base class for the definition of a package. Serializing this or any derived classes results in the description of the package (not serializable directly). All package definitions must inherit from this class and implement the required abstract methods. Attributes: name: The name of the package .. py:method:: model_post_init(__context) Initialize internal tracking structures .. py:method:: register_component(name, component) Register a component to be allocated to the pad ring and pins. Args: name: Component name component: Amaranth wiring.Component to allocate .. py:method:: allocate_pins(config, process, lockfile) Allocate package pins to the registered components. Pins should be allocated in the most usable way for users of the packaged IC. This default implementation uses _linear_allocate_components with self._allocate for the allocation strategy. Subclasses can override if they need completely different allocation logic. Args: config: ChipFlow configuration process: Semiconductor process lockfile: Optional existing lockfile to preserve allocations Returns: LockFile representing the pin allocation Raises: UnableToAllocate: If the ports cannot be allocated .. py:property:: bringup_pins :type: chipflow.packaging.pins.BringupPins :abstractmethod: Get the bringup pins for this package. To aid bringup, these are always in the same place for each package type. Should include core power, clock and reset. Power, clocks and resets needed for non-core are allocated with the port. Returns: BringupPins configuration .. py:class:: LinearAllocPackageDef Bases: :py:obj:`BasePackageDef`\ [\ :py:obj:`int`\ ] Base class for package types with linear pin/pad allocation. This is used for packages where pins are allocated from a simple linear ordering (e.g., numbered pins around a perimeter). Subclasses should populate self._ordered_pins in model_post_init before calling super().model_post_init(__context). Not directly serializable - use concrete subclasses. .. py:class:: BareDiePackageDef Bases: :py:obj:`chipflow.packaging.base.LinearAllocPackageDef` Definition of a package with pins on four sides. Sides are labeled north, south, east, west with an integer identifier within each side, indicating pads across or down from top-left corner. This is typically used for direct die attach without traditional packaging. Attributes: width: Number of die pads on top and bottom sides height: Number of die pads on left and right sides .. py:method:: model_post_init(__context) Initialize pin ordering .. py:property:: bringup_pins :type: chipflow.packaging.pins.BringupPins Bringup pins for bare die package .. py:class:: QuadPackageDef Bases: :py:obj:`chipflow.packaging.base.LinearAllocPackageDef` Definition of a quad flat package. A package with 'width' pins on the top and bottom and 'height' pins on the left and right. Pins are numbered anti-clockwise from the top left pin. This includes many common package types: - QFN: quad flat no-leads (bottom pad = substrate) - BQFP: bumpered quad flat package - BQFPH: bumpered quad flat package with heat spreader - CQFP: ceramic quad flat package - EQFP: plastic enhanced quad flat package - FQFP: fine pitch quad flat package - LQFP: low profile quad flat package - MQFP: metric quad flat package - NQFP: near chip-scale quad flat package - SQFP: small quad flat package - TQFP: thin quad flat package - VQFP: very small quad flat package - VTQFP: very thin quad flat package - TDFN: thin dual flat no-lead package - CERQUAD: low-cost CQFP Attributes: width: The number of pins across on the top and bottom edges height: The number of pins high on the left and right edges .. py:method:: model_post_init(__context) Initialize pin ordering .. py:property:: bringup_pins :type: chipflow.packaging.pins.BringupPins Bringup pins for quad package .. py:class:: GAPin Bases: :py:obj:`NamedTuple` Pin identifier for grid array packages (row letter, column number) .. py:class:: GALayout Bases: :py:obj:`enum.StrEnum` Layout type for grid array packages .. py:class:: GAPackageDef Bases: :py:obj:`chipflow.packaging.base.BasePackageDef`\ [\ :py:obj:`GAPin`\ ] Definition of a grid array package. Pins or pads are arranged in a regular array of 'width' by 'height'. Pins are identified by a 2-tuple of (row, column), counting from the bottom left when looking at the underside of the package. Rows are identified by letter (A-Z), columns by number. The grid may be complete or have missing pins (e.g., center cutout). This includes many package types: - CPGA: Ceramic Pin Grid Array - OPGA: Organic Pin Grid Array - SPGA: Staggered Pin Grid Array - CABGA: Chip Array Ball Grid Array - CBGA/PBGA: Ceramic/Plastic Ball Grid Array - CTBGA: Thin Chip Array Ball Grid Array - CVBGA: Very Thin Chip Array Ball Grid Array - DSBGA: Die-Size Ball Grid Array - FBGA: Fine Ball Grid Array / Fine Pitch Ball Grid Array - FCmBGA: Flip Chip Molded Ball Grid Array - LBGA: Low-Profile Ball Grid Array - LFBGA: Low-Profile Fine-Pitch Ball Grid Array - MBGA: Micro Ball Grid Array - MCM-PBGA: Multi-Chip Module Plastic Ball Grid Array - nFBGA: New Fine Ball Grid Array - SuperBGA (SBGA): Super Ball Grid Array - TABGA: Tape Array BGA - TBGA: Thin BGA - TEPBGA: Thermally Enhanced Plastic Ball Grid Array - TFBGA: Thin and Fine Ball Grid Array - UFBGA/UBGA: Ultra Fine Ball Grid Array - VFBGA: Very Fine Pitch Ball Grid Array - WFBGA: Very Very Thin Profile Fine Pitch Ball Grid Array - wWLB: Embedded Wafer Level Ball Grid Array Attributes: width: Number of columns height: Number of rows layout_type: Pin layout configuration channel_width: For PERIMETER/CHANNEL/ISLAND layouts island_width: For ISLAND layout, size of center island missing_pins: Specific pins to exclude (overrides layout) additional_pins: Specific pins to add (overrides layout) .. py:method:: model_post_init(__context) Initialize pin ordering .. py:property:: bringup_pins :type: chipflow.packaging.pins.BringupPins Bringup pins for grid array package .. py:property:: heartbeat :type: Dict[int, GAPin] Numbered set of heartbeat pins for the package .. py:class:: OFPin Bases: :py:obj:`NamedTuple` Pin identifier for Openframe package .. py:class:: OpenframePackageDef Bases: :py:obj:`chipflow.packaging.base.LinearAllocPackageDef` Definition of the ChipFoundry Openframe harness package. This is a standardized package/carrier used for open-source silicon projects, particularly with the ChipFoundry chipIgnite and OpenMPW programs. Attributes: name: Package name (default "openframe") .. py:method:: model_post_init(__context) Initialize pin ordering from GPIO list .. py:property:: bringup_pins :type: chipflow.packaging.pins.BringupPins Bringup pins for Openframe package .. py:exception:: UnableToAllocate Bases: :py:obj:`chipflow.ChipFlowError` Raised when pin allocation fails .. py:function:: load_pinlock() Load the pin lock file from the chipflow root. Returns: LockFile model Raises: ChipFlowError: If lockfile not found or malformed .. py:function:: lock_pins(config = None) Create or update the pin lock file for the design. This allocates package pins to component interfaces and writes the allocation to pins.lock. Will attempt to reuse previous pin positions if pins.lock already exists. Args: config: Optional Config object. If not provided, will be parsed from chipflow.toml Raises: ChipFlowError: If configuration is invalid or pin allocation fails .. py:class:: PinCommand(config) CLI command handler for pin-related operations. This class provides the command-line interface for managing pin allocations and lock files. .. py:method:: build_cli_parser(parser) Build the CLI parser for pin commands. Args: parser: argparse parser to add subcommands to .. py:method:: run_cli(args) Execute the CLI command. Args: args: Parsed command-line arguments .. py:method:: lock() Lock the pin map for the design. Will attempt to reuse previous pin positions.