Understanding a project's files

A project folder has nine files. Three of them do the work. Learn these three and the rest can wait.

The three that matter#

1. docs/DESIGN.mdwhat it must do
2. rtl/top.svhow it does it
3. tb/test_top.pyproof that it does
4. openlane/config.jsonhow it is built

Look at them#

In the Workspace terminal:

cd ~/project/mychip
ls -a
cat README.md
cat rtl/top.sv

README.md holds the starter's own steps, in order. Read it first.

The design: rtl/top.sv#

This is the whole design of the Blank starter: an 8-bit register.

module top (
    input  logic       clk,
    input  logic       rst_n,   // asynchronous, active low
    input  logic [7:0] d,
    output logic [7:0] q
);
    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n) q <= 8'd0;
        else        q <= d;
    end
endmodule

It has inputs, an output, and one rule: on each clock edge, q takes the value of d; in reset, q is 0.

The test: tb/test_top.py#

A Python file. It starts the clock, holds reset, then drives values in and checks what comes out. Each assert is one check.

The specification: docs/DESIGN.md#

What the design must do, in words: its ports, its behaviour, its reset, its latency and its clock. See Project specifications.

The rest#

constraints/clock.sdc, config/project.toml, synth.ys and Makefile tell the tools how to run. A starter's copies work as they are. The full list is in Project structure.