25 minv1.0

Linux debugging and EDA workflow

Learning objectives

Diagnose a failed tool command in a fixed order and collect enough evidence for another engineer to reproduce the result.

1 Objective→ 2 Learn→ 3 Example→ 4 Practice→ 5 Verify→ 6 Continue

How to study this lessonUnderstand the idea first. Use the example to see the behaviour, practise where provided, then make sure you can explain the result before continuing.

Explanation

Use a fixed diagnostic sequence

Do not change several things at once. Capture the failure, test one cause, make one safe correction, and rerun the original command.

Symptom	First checks	What the checks tell you
Command not found	`command -v tool`; `printf '%s\n' "$PATH"`	Whether the executable is installed and reachable.
File not found	`pwd`; `ls -l path`; `realpath path`	Whether the working directory and path are correct.
Permission denied	`id`; `namei -l path`; `stat path`	Which file or parent directory blocks access.
Missing library	`ldd executable`; package query	Which runtime dependency cannot be resolved.
Disk full	`df -h path`; `du -sh directory`	Filesystem capacity versus project usage.
Port busy	`ss -ltnp` when permitted	Which process owns the listening socket.
Process stuck	`ps -p PID -o pid,stat,etime,cmd`	Process identity, state, and elapsed time.

Tools such as strace and gdb can expose private paths, data, or process memory. Use them only in an approved lab with non-confidential inputs.

Worked example

Create a small evidence record for an optional simulator:

evidence="$HOME/asic-linux-practice/evidence"
mkdir -p "$evidence"

command -v iverilog > "$evidence/iverilog-path.txt" 2>&1
lookup_status=$?
printf 'lookup-status=%s\n' "$lookup_status" >> "$evidence/iverilog-path.txt"

if (( lookup_status == 0 )); then
    iverilog -V > "$evidence/iverilog-version.txt" 2>&1
fi

sha256sum "$evidence"/*.txt > "$evidence/checksums.txt"
cat "$evidence/iverilog-path.txt"

Expected result: an installed tool produces its path and version evidence. A missing tool produces a nonzero lookup status. Both are valid, truthful results.

Evidence for an RTL/DV run

Record:

Source revision and file list.
Working directory and exact command.
Tool name and version.
Relevant environment settings without secrets.
Exit status, standard output, and standard error.
Generated logs, reports, or waveforms.
Checksums and known limitations.

Common mistakes

Editing PATH before recording the original failure.
Applying a global LD_LIBRARY_PATH workaround.
Using chmod 777 for a permission problem.
Killing a process before verifying its PID and owner.
Reporting a tool run as successful when the executable was unavailable.
Downloading an unapproved binary or proprietary data to finish a lab.

Check yourself

Which evidence distinguishes an executable lookup failure from a runtime library failure?

Engineering practice

Practice: Linux debugging and EDA workflow

Task→Run / reason→Check result→Explain why

Create one controlled failure using a missing file, unavailable command, wrong working directory, or restricted file you own. Record the symptom, hypothesis, confirming check, correction, and verified result.

Practice work is non-certified and is not stored by ASIC Campus.