diff --git a/.github/skills/build-hw/SKILL.md b/.github/skills/build-hw/SKILL.md new file mode 100644 index 0000000000..25070dd4a1 --- /dev/null +++ b/.github/skills/build-hw/SKILL.md @@ -0,0 +1,89 @@ +--- +name: build-hw +description: Build a cycle-accurate simulation model of the Snitch cluster from RTL sources using Verilator, QuestaSim, or VCS. Use when you need to compile hardware for simulation before running software. +--- + +# Build Hardware Skill + +## Overview + +This skill provides instructions for building a cycle-accurate simulation model of the Snitch cluster from RTL sources. The simulation model is required to run software on Snitch without a physical chip. + +## Prerequisites + +- One of the following simulators installed: + - **Verilator** (open-source, recommended for containers) + - **QuestaSim** (proprietary, requires license) + - **VCS** (proprietary, requires license) + +## Description + +To build a simulation model of the Snitch cluster, run one of the following commands from the repository root: + +### Verilator +```bash +make verilator +``` +- Output: `target/sim/build/bin/snitch_cluster.vlt` executable +- Compiled sources: `target/sim/build/work-vlt` + +### QuestaSim (Questa) +```bash +make DEBUG=ON vsim +``` +- Output: `target/sim/build/bin/snitch_cluster.vsim` executable +- Compiled sources: `target/sim/build/work-vsim` +- **Important**: Always use `DEBUG=ON` flag to preserve visibility of all internal signals for waveform inspection + +### VCS +```bash +make vcs +``` +- Output: `target/sim/build/bin/snitch_cluster.vcs` executable +- Compiled sources: `target/sim/build/work-vcs` + +## Build Artifacts + +All build artifacts are located in `target/sim/build/`: + +- **Simulator-specific compilations**: + - `work-vlt/`: Verilator compilation + - `work-vsim/`: QuestaSim compilation + - `work-vcs/`: VCS compilation + +- **Common C++ testbench sources**: `work/` (includes frontend server) + +- **Executable scripts**: `bin/snitch_cluster.` (vlt, vsim, or vcs) + +Executables in `bin/` are ready to run software simulations. + +## Configuration + +By default, the hardware is built using the configuration from `cfg/default.json`. + +### Using a Custom Configuration + +To override the default configuration: + +```bash +make CFG_OVERRIDE=cfg/omega.json vsim +``` + +All available configurations are contained in the `cfg/` folder. + +### Configuration Persistence + +When you specify `CFG_OVERRIDE` on the command line: +- The configuration is automatically stored in `cfg/lru.json` +- Successive `make` invocations automatically use `cfg/lru.json` +- You can omit `CFG_OVERRIDE` in subsequent builds unless you want to change the configuration + +## Notes + +- All paths are relative to the repository root +- Software built for simulation must use the same hardware configuration used for the simulation model + +## Related Skills + +- **build-sw**: Compile software binaries to run on the compiled hardware model +- **run-sim**: Run simulations with the built hardware and compiled software diff --git a/.github/skills/build-sw/SKILL.md b/.github/skills/build-sw/SKILL.md new file mode 100644 index 0000000000..da58c0e10e --- /dev/null +++ b/.github/skills/build-sw/SKILL.md @@ -0,0 +1,78 @@ +--- +name: build-sw +description: Compile software for the Snitch cluster, including the runtime library and applications. Use when you need to build ELF binaries for simulation. +--- + +# Build Software Skill + +## Overview + +This skill provides instructions for compiling software for the Snitch cluster. The software stack depends on the hardware configuration, so the same configuration used to build the hardware must be used when building software. + +## Description + +### Building All Software Targets + +To build all software targets defined in the repository (runtime library and all kernels): + +```bash +make DEBUG=ON sw -j +``` + +**Parameters**: +- `DEBUG=ON`: Generates disassemblies and enables debugging symbols. This is required for trace annotation +- `-j`: Parallel build + +### Building Specific Software Targets + +To build a single software target (e.g., a kernel): + +```bash +make DEBUG=ON -j +``` + +**Example**: +```bash +make DEBUG=ON axpy -j +``` + +**Note**: All software targets have unique names distinct from any other Make target, and every kernel can be individually built using the kernel name as a target. + +## Build Artifacts + +Build artifacts are stored in the build directory of each kernel: + +- **Location**: `/build/` +- **Compiled executable**: `.elf` +- **Disassembly**: `.dump` (generated with `DEBUG=ON`) + +**Example** (AXPY application): +``` +sw/kernels/blas/axpy/build/ +├── axpy.elf # Compiled executable +├── axpy.dump # Disassembly (with DEBUG=ON) +└── [other artifacts] +``` + +## Configuration Management + +### Critical Requirement + +**The software stack depends on the hardware configuration file.** Make sure you always build the software with the same configuration of the hardware you are going to run it on. + +### Configuration Tracking + +The hardware configuration is automatically tracked: +- When you override the configuration during hardware build, it's stored in `cfg/lru.json` +- Successive Make invocations automatically pick up `cfg/lru.json` +- Ensure software is built after hardware with the same configuration + +## Important Notes + +- Software must match the hardware configuration - always build them together +- The `DEBUG=ON` flag is essential for trace annotation + +## Related Skills + +- **build-hw**: Build the hardware simulation binary before building software +- **run-sim**: Execute the compiled software binaries on the built hardware diff --git a/.github/skills/run-sim/SKILL.md b/.github/skills/run-sim/SKILL.md new file mode 100644 index 0000000000..185550bc44 --- /dev/null +++ b/.github/skills/run-sim/SKILL.md @@ -0,0 +1,111 @@ +--- +name: run-sim +description: Execute software binaries on a Snitch cluster simulation using previously built hardware. Use when you need to run simulations and capture execution traces from compiled software. +--- + +# Run Simulation Skill + +## Overview + +This skill provides instructions for executing software on a previously built Snitch cluster simulation model. After building hardware and compiling software, use this skill to run simulations and capture execution traces. If the user doesn't specify which simulator to use, and this is not implicit from the context, then ask before taking any further action. + +## Prerequisites + +- Hardware simulation binary built (from the `build-hw` skill) +- Software executable compiled (typically with `.elf` extension) + +## Description + +### Basic Simulation Execution + +To run a compiled software binary on the Snitch cluster simulator, execute one of the following commands depending on which simulator was used to build the hardware: + +#### Verilator +```bash +snitch_cluster.vlt +``` +- Example: `snitch_cluster.vlt sw/kernels/blas/axpy/build/axpy.elf` +- Output: Console output + log files in simulation directory + +#### QuestaSim (Questa) +```bash +snitch_cluster.vsim +``` +- Example: `snitch_cluster.vsim sw/kernels/blas/axpy/build/axpy.elf` +- Output: Console output + log files in simulation directory + +#### VCS +```bash +snitch_cluster.vcs +``` +- Example: `snitch_cluster.vcs sw/kernels/blas/axpy/build/axpy.elf` +- Output: Console output + log files in simulation directory + +#### Using Make Target (QuestaSim) + +For convenience, a Make target alias is provided: +```bash +make vsim-run BINARY= SIM_DIR= +``` + +**Parameters**: +- `BINARY`: Absolute or relative path to the ELF file (path is relative to simulation directory if relative) +- `SIM_DIR`: Directory where simulation artifacts will be created (default: `test`) + +**Example**: +```bash +make vsim-run BINARY=$PWD/sw/kernels/blas/axpy/build/axpy.elf SIM_DIR=test +``` + +### Kernel Verification + +To verify results, prepend a verification script to the simulation command: + +```bash +sw/kernels/blas/axpy/scripts/verify.py snitch_cluster.vlt sw/kernels/misc/tutorial/build/tutorial.elf +``` + +Check the exit code to confirm verification success (exit code $0$ means success): + +```bash +echo $? +``` + +**Note**: Not all kernels provide a verification script. Only add the verification script when simulating a kernel that provides one at the path `/scripts/`. + +#### Verification with the Make Target (QuestaSim) + +When using the `vsim-run` alias, pass the verification script with `VERIFY_PY`: + +```bash +make vsim-run BINARY=$PWD/sw/kernels/blas/axpy/build/axpy.elf VERIFY_PY=$PWD/sw/kernels/blas/axpy/scripts/verify.py +``` + +The `VERIFY_PY` path must be absolute or relative to the simulation directory. + +## Path Resolution + +- Simulator binaries can be invoked from any directory +- The `target/sim/build/bin/` folder, containing the simulator binaries, is automatically added to the `$PATH`, so the simulator binaries don't need to be prefixed +- Adapt the relative path to the software binary accordingly, or use absolute paths + +## Output Files + +After simulation completion, the simulation directory will contain: + +- **Trace files** (`logs/` subdirectory): + - One file per core, identified by hart ID + - `.dasm` extension (non-human-readable) + - Can be converted to human-readable format (see `annotate-traces` skill) + +- **Simulation-specific artifacts**: Log files and outputs from the simulator + +## Important Notes + +- Ensure the software binary was compiled with the same hardware configuration as the simulator binary +- Log files will be overwritten if you run another simulation in the same directory + +## Related Skills + +- **build-hw**: Build the hardware simulation binary before running simulations +- **build-sw**: Compile software binaries for simulation (referenced in `build-hw`) diff --git a/.gitignore b/.gitignore index 9b07c09fce..969ba25a97 100644 --- a/.gitignore +++ b/.gitignore @@ -18,7 +18,6 @@ AN.DB/ work.lib++/ # Miscellaneous -.vscode/ __pycache__ gmon.out diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000000..7fae291d52 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,6 @@ +{ + "chat.tools.terminal.terminalProfile.linux": { + "path": "bash", + "args": ["--rcfile", "${workspaceFolder}/.vscode/vscode_bashrc"] + } +} \ No newline at end of file diff --git a/.vscode/vscode_bashrc b/.vscode/vscode_bashrc new file mode 100644 index 0000000000..e3449feaee --- /dev/null +++ b/.vscode/vscode_bashrc @@ -0,0 +1,12 @@ +# VS Code shell integration +if [[ "$TERM_PROGRAM" == "vscode" ]]; then + . "$(code --locate-shell-integration-path bash)" +fi + +# Source the user's .bashrc if it exists +if [ -f ~/.bashrc ]; then + source ~/.bashrc +fi + +# Set up the environment for IIS development +source ./iis-setup.sh