RTL/DV project organization, file lists and Git

Explanation

Why project structure matters

Simulation and synthesis tools create executables, logs, reports, temporary files, and waveforms. If generated output is mixed with source code, it becomes difficult to review changes, reproduce a run, or clean the project safely.

A small RTL/DV project can use this structure:

The project README should state the supported tool versions, setup steps, compile command, run command, expected result, and known limitations.

Create the project safely

project="$HOME/asic-linux-practice/counter-project"
mkdir -p "$project"/{rtl,tb,scripts,filelists,docs,constraints,sim,logs,waves,reports}
cd "$project"
pwd
find . -maxdepth 1 -type d -print | sort

Expected result: the project root contains separate source, script, documentation, build, log, waveform, and report directories.

Use an ordered source file list

Many EDA tools accept a file list. Order matters when packages or definitions must be read before modules that use them.

Example filelists/rtl.f:

rtl/counter.v

Example filelists/sim.f:

-f filelists/rtl.f
tb/tb_counter.v

Use paths relative to the documented project root unless the tool flow requires another convention. Do not place machine-specific home-directory paths in a shared file list.

To inspect candidate files before writing a list:

find rtl tb -type f \( -name '*.v' -o -name '*.sv' \) -print | sort

Review the result. Package dependencies and required compile order may mean that an automatically sorted list is not the correct final file list.

Ignore generated output

Create .gitignore in the project root:

# Generated build and run output
sim/
logs/
waves/
reports/

# Editor temporary files
*.swp
*.swo
*~

# Common waveform and simulator artifacts
*.vcd
*.fst
*.wlf
simv

.gitignore affects untracked files. It does not remove a file that Git already tracks.

Essential Git commands

Always run git status and review diffs before committing. Stage named paths rather than using a broad command when generated or confidential files may be present.

Remote operations such as clone, fetch, pull, and push depend on the team repository and access policy. Use the repository URL and branch workflow provided by the project owner.

Worked example

Create two small source files and initialize a local repository:

cd "$HOME/asic-linux-practice/counter-project"
printf 'module counter;\nendmodule\n' > rtl/counter.v
printf 'module tb_counter;\nendmodule\n' > tb/tb_counter.v
printf 'rtl/counter.v\n' > filelists/rtl.f
printf '%s\n' '-f filelists/rtl.f' 'tb/tb_counter.v' > filelists/sim.f
printf '%s\n' 'sim/' 'logs/' 'waves/' 'reports/' '*.swp' '*.vcd' '*.fst' 'simv' > .gitignore

git init
git status --short
git add .gitignore rtl/counter.v tb/tb_counter.v filelists/rtl.f filelists/sim.f
git diff --cached

Expected result: git status --short initially marks the new files as untracked. After git add, they appear as staged. git diff --cached shows only the source, file lists, and .gitignore selected for the first commit.

Before committing, Git needs an approved author identity. Use the identity required by the training or company repository. For a disposable local lab only, an instructor may provide repository-local settings:

git config user.name "Training User"
git config user.email "training@example.invalid"
git commit -m "Add counter project skeleton"
git log --oneline --decorate -n 3

These commands omit --global, so the sample identity affects only this disposable repository.

Review a source change

printf '// Four-bit counter\n' | cat - rtl/counter.v > rtl/counter.v.new
mv rtl/counter.v.new rtl/counter.v
git status --short
git diff -- rtl/counter.v

Read the diff before staging. A line beginning with + was added; a line beginning with - was removed. Diff markers are review notation and are not part of the Verilog file.

Common mistakes

• Running git init in the wrong directory.
• Committing simulator executables, waveforms, large logs, credentials, or proprietary data.
• Generating file lists without checking compile order.
• Using absolute personal paths in shared scripts or file lists.
• Running git add . without reviewing untracked output.
• Committing without reading git diff --cached.
• Using git restore before saving a change that is still needed.
• Editing generated files instead of their source or generation script.

Check yourself

Why should rtl/ and tb/ be separated from sim/ and waves/? What does git diff --cached show? Why can an alphabetically generated file list be incorrect?