Edge Bringup

Edge bring-up

Start by reading the root README.md. Run scripts/check-env.sh from this skill to inspect the host without changing it. Install dependencies only when the user asks for installation or setup.

Prepare the environment

Do not add a uv-managed Python installation directly to the user's global PATH. The repository owns its Python environment through .venv, pyproject.toml, and uv.lock. Run Python entry points with .venv/bin/python, set PYTHON=.venv/bin/python for maintained shell wrappers, or activate .venv explicitly.

For macOS with Homebrew:

brew install verilator llvm lld python cmake

The maintained scripts default to Homebrew LLVM paths under /opt/homebrew/opt/llvm and /opt/homebrew/opt/lld. On Intel macOS, or when Homebrew uses another prefix, export LLVM_PREFIX="$(brew --prefix llvm)" and LLD_PREFIX="$(brew --prefix lld)".

For Ubuntu:

sudo apt-get update
sudo apt-get install -y build-essential git cmake verilator llvm clang lld python3 python3-pip python3-venv

Why the maintained flow uses LLVM

Use the standard Clang/LLVM toolchain for both sides of the build:

• clang, clang++, and LLD build the freestanding RV64 target program;
• Verilator comes from the host package manager, translates the RTL into C++, and that generated host simulator is compiled with Clang; and
• the same compiler family is available on both macOS and Ubuntu, avoiding a separate RV64 GCC cross-toolchain and its associated setup and maintenance.

This choice is also practical for simulator builds. Large Verilator-generated C++ builds with GCC have repeatedly exhausted memory on the maintained macOS development machines; Clang has been more reliable there.

Do not add or prefer a GCC/G++ flow solely for possible differences in RV64 instruction selection or scheduling. The ASIC command path is relatively insensitive to those differences: performance-critical kernels explicitly manage DMA, DTCM placement, synchronization, circular buffering, and accelerator overlap. Those kernel-level choices dominate here, so an occasional GCC code-generation advantage would have little system-level effect and does not justify maintaining another cross-platform compiler stack.

When building the Verilator simulator, select Clang explicitly if the host defaults to another compiler:

CC=clang CXX=clang++ ./scripts/build-verilator.sh

Install uv using its maintained installation instructions when uv is absent: https://docs.astral.sh/uv/getting-started/installation/. The environment checker and public build scripts recognize both unversioned LLVM tools and Ubuntu names such as llvm-objdump-19, llvm-objcopy-19, and ld.lld-19. Environment variables such as CLANG, CLANGXX, LLVM_OBJCOPY, LLVM_OBJDUMP, and LLD remain explicit overrides.

Initialize only required public submodules:

git submodule update --init \
  src/edge-e3enc src/edge-32 third_party/coremark third_party/openc906
./scripts/setup-python.sh

Keep src/edge-e3 and src/edge-asic deinitialized for the public flow. Never initialize or use a private/non-public checkout merely to make a public test pass.

scripts/setup-python.sh selects one mutually exclusive PyTorch extra from pyproject.toml and runs uv sync:

• If nvidia-smi is absent, cannot query a GPU, or cannot report a supported CUDA driver level, select cpu.
• Select cu126 for a reported CUDA capability from 12.6 through 12.x, cu130 for 13.0–13.1, and cu132 for 13.2 or newer.
• After installation, require the CPU build to report no CUDA runtime, or the selected CUDA build to pass torch.cuda.is_available() and name its GPU.

For deterministic diagnosis or CI, override auto-detection explicitly:

./scripts/setup-python.sh cpu
./scripts/setup-python.sh cu126
./scripts/setup-python.sh cu130
./scripts/setup-python.sh cu132

The nvidia-smi CUDA value is the newest runtime supported by the installed driver, not a requirement to install a matching system CUDA toolkit. The PyTorch wheel supplies its runtime; nvcc is only needed for compiling custom CUDA extensions.