Intro to `chipflow.toml`

The chipflow.toml file provides configuration for your design with the ChipFlow platform.

Let’s start with a typical example:

[chipflow]
project_name = "test-chip"

[chipflow.top]
soc = "my_design.design:MySoC"

[chipflow.steps]
silicon = "chipflow_lib.steps.silicon:SiliconStep"

[chipflow.clocks]
default = 'sys_clk'

[chipflow.resets]
default = 'sys_rst_n'

[chipflow.silicon]
process = "gf130bcd"
package = "pga144"

[chipflow.silicon.pads]
# System
sys_clk   = { type = "clock", loc = "114" }
sys_rst_n = { type = "reset", loc = "115" }

[chipflow.silicon.power]
dvss0        = { type = "power", loc =   "1" }
dvdd0        = { type = "ground", loc =   "9" }
vss0         = { type = "power", loc =  "17" }
vdd0         = { type = "ground", loc =  "25" }
dvss1        = { type = "power", loc =  "33" }
dvdd1        = { type = "ground", loc =  "41" }
vss1         = { type = "power", loc =  "49" }
vdd1         = { type = "ground", loc =  "57" }
dvss2        = { type = "power", loc =  "65" }
dvdd2        = { type = "ground", loc =  "73" }
vss2         = { type = "power", loc =  "81" }
vdd2         = { type = "ground", loc =  "89" }
dvss3        = { type = "power", loc =  "97" }
dvdd3        = { type = "ground", loc = "105" }
vss3         = { type = "power", loc = "113" }
vdd3         = { type = "ground", loc = "121" }
dvss4        = { type = "power", loc = "129" }
dvdd4        = { type = "ground", loc = "137" }

`[chipflow]`

[chipflow]
project_name = "my_project"

The project_name is a human-readable identifier for this project. If not set, the tool and library will use the project name configured in pyproject.toml.

`[chipflow.top]`

[chipflow.top]
soc = "my_design.design:MySoC"

This section outlines the design modules that need to be instantiated. A new top module will be automatically generated, incorporating all specified modules along with their interfaces. Each entry follows the format <instance name> = <module class path>.

The instance name is the name the python object will be given in your design, and the module class path

module class path: The module class path offers a way to locate Python objects as entry points. It consists of a module’s qualified name followed by a colon (:) and then the qualified name of the class within that module.

`[chipflow.steps]`

The steps section allows overriding or addition to the standard steps available from chipflow_lib.

For example, if you want to override the standard silicon preparation step, you could derive from chipflow_lib.steps.silicon.SiliconStep, add your custom functionality and add the following to your chipflow.toml, with the appropriate module class path:

[chipflow.steps]
silicon = "my_design.steps.silicon:SiliconStep"

You probably won’t need to change these if you’re starting from an example repository.

`[chipflow.clocks]`

[chipflow.clocks]
default = 'sys_clk'

This section links the clock domains utilized in the design to specific pads. These pads need to be specified in the [silicon.pads] section with the :term:type set to :term:clock. The default clock domain is associated with the Amaranth sync clock domain. Currently, only one default clock domain is supported.

`[chipflow.resets]`

[chipflow.resets]
default = 'sys_rst_n'

This section identifies the input pads designated for reset functionality. These pads need to be specified in the [silicon.pads] section with the :term:type set to :term:reset. The logic that synchronizes the reset signal with the clock will be generated automatically.

`[chipflow.silicon]`

[chipflow.silicon]
process = "ihp_sg13g2"
package = "pga144"

The silicon section sets the Foundry process (i.e. PDK) that we are targeting for manufacturing, and the physical package (pad ring) we want to place our design inside. You’ll choose the process and package based in the requirements of your design.

Available processes

Process	Supported pad rings	Notes
sky130	caravel	Skywater 130nm
gf180	caravel	GlobalFoundries 180nm
gf130bcd	pga144	GlobalFoundries 130nm BCD
ihp_sg13g2	pga144	IHP SG13G2 130nm SiGe

Available pad rings

Pad ring	Pad count	Pad locations	Notes

pga144	144	`1` … `144`
TBA			If you require a different pad ring, then please contact customer support.

`[silicon.pads]`

The silicon.pads section lists special pads. In general you are unlikely to need to add to this. Each pad specified with the name used by the design and two parameters: :term:type and loc.

[chipflow.silicon.pads]
sys_clk   = { type = "clock", loc = "114" }
sys_rst_n = { type = "reset", loc = "115" }

In the above example two pads specified, sys_clk pad for clock input and sys_rst_n for reset.

loc: This is the physical location of the pad on your chosen pad ring. How these are indexed varies by the pad ring.
type: The :term:type for each pad can be set to one of :term:clock or :term:reset.
clock: External clock input.
reset: External reset input.

`[silicon.power]`

This section outlines the connection of pads to the power supply available for the selected process and package. These pads are declared with the :term:type and :term:loc parameters, similar to the [silicon.pads] section. Note that in this context, the :term:type parameter can only be ground or power.

This is a work in progress, and currently you can use the defaults provided by customer support.

Intro to chipflow.toml

[chipflow]

[chipflow.top]

[chipflow.steps]

[chipflow.clocks]

[chipflow.resets]

[chipflow.silicon]