Project structure

Every file in a project, what it is for, and which ones must stay where they are.

EngineerStudentDeveloper 1 min read · Updated 2026-10-05

On this page

A project is a folder under ~/project. This is what a project created from a starter contains.

text

mychip/
  rtl/top.sv              the design
  tb/test_top.py          the test
  docs/DESIGN.md          the specification
  openlane/config.json    build settings
  constraints/clock.sdc   the clock constraint
  config/project.toml     project details
  synth.ys                the synthesis script
  Makefile                how the simulation is started
  README.md               the starter's own steps

The files#

Path	What it is	Change it to
`rtl/top.sv`	The design, in SystemVerilog. The top module is named `top`	Change what the chip does
`tb/test_top.py`	The cocotb test that Simulate runs	Change what is checked
`docs/DESIGN.md`	The specification	Record what the design must do
`openlane/config.json`	Build settings: clock port, clock period, die size	Change the layout build
`constraints/clock.sdc`	The clock constraint, in the standard SDC format	Keep in step with the clock period in `config.json`
`config/project.toml`	The project's name, top module, clock, reset and target	Rarely needed
`synth.ys`	The script the Synthesize stage runs	Rarely needed
`Makefile`	Starts the simulation with cocotb and Icarus Verilog	Rarely needed
`README.md`	The starter's steps, in order	Read it first

Files the tools create#

Path	Created by	What it is
`sim_build/top.fst`	Simulate	The waveform
`results.xml`	Simulate	The test result
`reports/synth.log`	Synthesize	The synthesis log, ending in the cell count
`reports/top_synth.v`	Synthesize	The block-level netlist. The schematic is drawn from this
`reports/top_gates.v`	Synthesize	The gate-level netlist
`openlane/runs/<run id>/`	Build the chip	Every working file of one build. These are large

You do not need to edit any of these.

Rules#

The top module is named top, in rtl/top.sv.
A design is one file today. The starter's Makefile, synth.ys and config.json all name that one file.
A guided project has a START_HERE.md in place of a README.md.

Configuration filesThe actual fields of openlane/config.json, config/project.toml and constraints/clock.sdc, with the values a starter ships with.
Understanding a project's filesThe three files that do the work, and how they connect to the three stages.

Something unclear or missing? Send feedbackSign in and use Feedback to tell us.

Project structure

The files#

Files the tools create#

Rules#

Related