Platform API Reference

This page documents the complete public API of the chipflow_lib.platform module.

All symbols listed here are re-exported from submodules for convenience and can be imported directly from chipflow_lib.platform.

Platforms

class chipflow_lib.platform.sim.SimPlatform(config)

Bases: object

add_file(filename, content)
build(e, top)
instantiate_ports(m)
Parameters:

m (Module)

class chipflow_lib.platform.silicon.SiliconPlatform(config)

Bases: object

Parameters:

config (Config)

add_file(filename, content)
build(elaboratable, name='top')
get_io_buffer(buffer)
instantiate_ports(m)
Parameters:

m (Module)

property ports
request(name, **kwargs)
class chipflow_lib.platform.silicon.SiliconPlatformPort(name, port_desc)

Bases: PortLike, Generic[Pin]

Parameters:

  • name (str)

  • port_desc (PortDesc)

property direction

Direction of the port.

Return type:

Direction

property i
property ie
instantiate_toplevel()
property invert
property iomodel: IOModel
property name: str
property o
property oe
property pins: List[Pin]
wire_up(m, wire)
class chipflow_lib.platform.software.SoftwarePlatform(config)

Bases: object

build(m, top)

Build Steps

class chipflow_lib.platform.base.StepBase(config={})

Bases: ABC

Base class for ChipFlow build steps.

build(*args)

builds the design

build_cli_parser(parser)

Build the cli parser for this step

run_cli(args)

Called when this step’s is used from chipflow command

class chipflow_lib.platform.sim_step.SimStep(config)

Bases: StepBase

build(*args)

Builds the simulation model for the design

build_cli_parser(parser)

Build the cli parser for this step

check(*args)

Run the simulation and check events against reference (tests/events_reference.json). Will ensure that the simulation and the software are both built.

run(*args)

Run the simulation. Will ensure that the simulation and the software are both built.

run_cli(args)

Called when this step’s is used from chipflow command

property sim_dir
class chipflow_lib.platform.silicon_step.SiliconStep(config)

Bases: object

Step to Prepare and submit the design for an ASIC.

build_cli_parser(parser)
determine_submission_name()
prepare()

Elaborate the design and convert it to RTLIL.

Returns the path to the RTLIL file.

run_cli(args)
submit(rtlil_path, args)

Submit the design to the ChipFlow cloud builder.

Options:

–dry-run: Don’t actually submit –wait: Wait until build has completed. Use ‘-v’ to increase level of verbosity –log-file <file>: Log full debug output to file

class chipflow_lib.platform.software_step.SoftwareStep(config)

Bases: StepBase

Base step to build the software.

build(*args)

Build the software for your design

build_cli_parser(parser)

Build the cli parser for this step

doit_build_module = None
run_cli(args)

Called when this step’s is used from chipflow command

class chipflow_lib.platform.board_step.BoardStep(config, platform)

Bases: StepBase

Build the design for a board.

build(*args)

Build for the given platform

build_cli_parser(parser)

Build the cli parser for this step

run_cli(args)

Called when this step’s is used from chipflow command

IO Signatures

Base IO Signatures

class chipflow_lib.platform.io.iosignature.IOSignature(**kwargs)

Bases: Signature

An Amaranth Signature used to decorate wires that would usually be brought out onto a port on the package. This class is generally not directly used. Instead, you would typically utilize the more specific InputIOSignature, OutputIOSignature, or BidirIOSignature for defining pin interfaces.

Parameters:

kwargs (Unpack[IOModel])

annotations(obj, /)

Annotate an interface object.

Subclasses of Signature may override this method to provide annotations for a corresponding interface object. The default implementation provides none.

See amaranth.lib.meta for details.

Returns:

tuple()

Return type:

iterable of Annotation

property direction: Direction

The direction of the IO port

property invert: Iterable[bool]

A tuple as wide as the IO port, with a bool for the polarity inversion for each wire

property options: IOModelOptions

Options set on the io port at construction

property width: int

The width of the IO port, in wires

class chipflow_lib.platform.io.iosignature.OutputIOSignature(width, **kwargs)

Bases:

This creates an Amaranth Signature which is then used to decorate package output signals intended for connection to the physical pads of the integrated circuit package.

Parameters:

  • width (int) – specifies the number of individual output wires within this port, each of which will correspond to a separate physical pad on the integrated circuit package.

  • kwargs (Unpack[IOModelOptions])

class chipflow_lib.platform.io.iosignature.InputIOSignature(width, **kwargs)

Bases:

This creates an Amaranth Signature which is then used to decorate package input signals intended for connection to the physical pads of the integrated circuit package.

Parameters:

  • width (int) – specifies the number of individual input wires within this port, each of which will correspond to a separate physical pad on the integrated circuit package.

  • kwargs (Unpack[IOModelOptions])

class chipflow_lib.platform.io.iosignature.BidirIOSignature(width, **kwargs)

Bases:

This creates an Amaranth Signature which is then used to decorate package bi-directional signals intended for connection to the physical pads of the integrated circuit package.

Parameters:

  • width (int) – specifies the number of individual input/output wires within this port. Each pair of input/output wires will correspond to a separate physical pad on the integrated circuit package.

  • kwargs (Unpack[IOModelOptions])

Protocol-Specific Signatures

class chipflow_lib.platform.io.signatures.UARTSignature(*args, **kwargs)

Bases: Signature

annotations(obj, /)

Annotate an interface object.

Subclasses of Signature may override this method to provide annotations for a corresponding interface object. The default implementation provides none.

See amaranth.lib.meta for details.

Returns:

tuple()

Return type:

iterable of Annotation

class chipflow_lib.platform.io.signatures.GPIOSignature(*args, **kwargs)

Bases: Signature

annotations(obj, /)

Annotate an interface object.

Subclasses of Signature may override this method to provide annotations for a corresponding interface object. The default implementation provides none.

See amaranth.lib.meta for details.

Returns:

tuple()

Return type:

iterable of Annotation

class chipflow_lib.platform.io.signatures.SPISignature(*args, **kwargs)

Bases: Signature

annotations(obj, /)

Annotate an interface object.

Subclasses of Signature may override this method to provide annotations for a corresponding interface object. The default implementation provides none.

See amaranth.lib.meta for details.

Returns:

tuple()

Return type:

iterable of Annotation

class chipflow_lib.platform.io.signatures.I2CSignature(*args, **kwargs)

Bases: Signature

annotations(obj, /)

Annotate an interface object.

Subclasses of Signature may override this method to provide annotations for a corresponding interface object. The default implementation provides none.

See amaranth.lib.meta for details.

Returns:

tuple()

Return type:

iterable of Annotation

class chipflow_lib.platform.io.signatures.QSPIFlashSignature(*args, **kwargs)

Bases: Signature

annotations(obj, /)

Annotate an interface object.

Subclasses of Signature may override this method to provide annotations for a corresponding interface object. The default implementation provides none.

See amaranth.lib.meta for details.

Returns:

tuple()

Return type:

iterable of Annotation

class chipflow_lib.platform.io.signatures.JTAGSignature(*args, **kwargs)

Bases: Signature

annotations(obj, /)

Annotate an interface object.

Subclasses of Signature may override this method to provide annotations for a corresponding interface object. The default implementation provides none.

See amaranth.lib.meta for details.

Returns:

tuple()

Return type:

iterable of Annotation

Software Integration

class chipflow_lib.platform.io.signatures.SoftwareDriverSignature(members, **kwargs)

Bases: Signature

Parameters:

kwargs (Unpack[DriverModel])

class chipflow_lib.platform.io.signatures.SoftwareBuild(*, sources, includes=[], include_dirs=[], offset=0)

Bases: object

This holds the information needed for building software and providing the built outcome

Parameters:

  • sources (list[Path])

  • includes (list[Path])

  • include_dirs (list[Path])

  • offset (int)

build_dir: Path
filename: Path
include_dirs: list[Path]
includes: list[Path]
offset: int
sources: list[Path]
type: Literal['SoftwareBuild'] = 'SoftwareBuild'
chipflow_lib.platform.io.signatures.attach_data(external_interface, component, data)
Parameters:

IO Configuration

class chipflow_lib.platform.io.iosignature.IOModel

Setting for IO Ports (see also base class IOModelOptions)

Attributes:

  • direction – io.Direction.Input, io.Direction.Output or io.Direction.Bidir

  • width – width of port, default is 1

buffer_in: NotRequired[bool]
buffer_out: NotRequired[bool]
clock_domain: NotRequired[str]
direction: <lambda>, return_type=PydanticUndefined, when_used=always)]
individual_oe: NotRequired[bool]
init: NotRequired[int | bool]
init_oe: NotRequired[int | bool]
invert: NotRequired[bool | Tuple[bool, ...]]
sky130_drive_mode: NotRequired[Sky130DriveMode]
trip_point: NotRequired[IOTripPoint]
width: int
class chipflow_lib.platform.io.iosignature.IOModelOptions

Options for an IO pad/pin.

Attributes:

  • invert – Polarity inversion. If the value is a simple bool, it specifies inversion for the entire port. If the value is an iterable of bool, the iterable must have the same length as the width of io, and the inversion is specified for individual wires.

  • individual_oe – controls whether each output wire is associated with an individual Output Enable bit or if a single OE bit will be used for entire port. The default value is False (indicating that a single OE bit controls the entire port).

  • power_domain – The name of the I/O power domain. NB there is only one of these, so IO with multiple power domains must be split up.

  • clock_domain – the name of the I/O’s clock domain (see Amaranth.ClockDomain). NB there is only one of these, so IO with multiple clocks must be split up.

  • buffer_in – Should the IO pad have an input buffer?

  • buffer_out – Should the IO pad have an output buffer?

  • sky130_drive_mode – Drive mode for output buffer on sky130

  • trip_point – Trip Point configutation for input buffer

  • init – The value for the initial values of the port

  • init_oe – The value for the initial values of the output enable(s) of the port

buffer_in: NotRequired[bool]
buffer_out: NotRequired[bool]
clock_domain: NotRequired[str]
individual_oe: NotRequired[bool]
init: NotRequired[int | bool]
init_oe: NotRequired[int | bool]
invert: NotRequired[bool | Tuple[bool, ...]]
sky130_drive_mode: NotRequired[Sky130DriveMode]
trip_point: NotRequired[IOTripPoint]
class chipflow_lib.platform.io.iosignature.IOTripPoint(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Models various options for trip points for inputs. Depending on process and cell library, these may be statically or dynamically configurable.

You will get an error if the option is not available with the chosen process and cell library

CMOS = 'cmos'
SCHMITT_TRIGGER = 'schmitt_trigger'
TTL = 'ttl'
VCORE = 'vcore'
VREF = 'vref'
class chipflow_lib.platform.io.sky130.Sky130DriveMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Models the potential drive modes of an SkyWater 130 IO cell [sky130_fd_io__gpiov2](https://skywater-pdk.readthedocs.io/en/main/contents/libraries/sky130_fd_io/docs/user_guide.html) These are both statically configurable and can be set at runtime on the :py:mod:drive_mode.Sky130Port lines on the port.

OPEN_DRAIN_STRONG_DOWN = 'open_drain_strong_down'
OPEN_DRAIN_STRONG_UP = 'open_drain_strong_up'
STRONG_UP_STRONG_DOWN = 'strong_up_strong_down'
STRONG_UP_WEAK_DOWN = 'strong_up_weak_down'
WEAK_UP_STRONG_DOWN = 'weak_up_strong_down'
WEAK_UP_WEAK_DOWN = 'weak_up_weak_down'

Utility Functions

chipflow_lib.platform.base.setup_amaranth_tools()

Configure environment for Amaranth/WASM tools.

chipflow_lib.utils.top_components(config)

Return the top level components for the design, as configured in chipflow.toml.

Parameters:

config (Config) – The parsed chipflow configuration

Returns:

Dictionary mapping component names to instantiated Component objects

Raises:

ChipFlowError – If component references are invalid or instantiation fails

Return type:

Dict[str, wiring.Component]

chipflow_lib.utils.get_software_builds(m, component)

Extract software build information from a component’s interfaces.

Parameters:

  • m – Module containing the component

  • component (str) – Name of the component

Returns:

Dictionary of interface names to SoftwareBuild objects

Constants

chipflow_lib.platform.io.iosignature.IO_ANNOTATION_SCHEMA

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.