Skip to content

Development Notes

This page is for contributors. It covers extending the core, adding tests, or building on this model for a larger system.


Repository layout

SparcV8_core/
  model/
    cpp_common_code/          SparcCore, the core, timing-agnostic. Shared by both drivers.
                                mmu/, cache/, devices/ and apara/ hold the MMU, the L1 caches,
                                the peripheral devices and the APARA engine.
    sitar_component_models/    The reusable Sitar procedures and modules every configuration
                                 is built from.
    system_models/              One folder per configuration (core_only/, core_mmu/, ...,
                                  sparc_apara/), each with its own cpp_model/ (0-delay driver)
                                  and sitar_model/ (Sitar-timed driver) subfolders.
    build_scripts/               Shared build logic every configuration's own build.sh invokes.
  validation/
    asm/                Instruction-level assembly test suite.
    C/                  Self-validating bare-metal C mini-benchmark suite, including the
                          component suites C/mmu/, C/devices/ and C/caches/.
    sparc_apara/        The SPARC using the APARA engine (sparc_apara only).
    apara/              The APARA engine's own test suites and their runner (apara only).
    test_simple_ADD/    Canonical copy of the bundled walkthrough example.
  compiler/               SPARC V8 cross-toolchain + build scripts.
    include/                Bare-metal C routines for the devices and the APARA engine.
    apara/                  The APARA engine's assembler, disassembler and C compiler.
  debug/                   gdb convenience commands (sparc.gdb) for runtime inspection.
  docs/                    This documentation site.
    source/                  The .md pages you're reading (MkDocs docs_dir).
    generated_site/           Prebuilt, committed output. See "Building the docs site" below.
    mkdocs.yml, requirements.txt, *_pygments_lexer/  Build config, pinned dependencies, and
      vendored syntax lexers (Sitar, SPARC assembly, APARA mcode).
    compliance/               Documented, specific divergences from AJIT's own reference results.
  log_viewer/              Offline browser tool for viewing an instruction/state trace.

Each of model/cpp_common_code/, model/sitar_component_models/, and every model/system_models/<config>/{cpp_model,sitar_model}/ has its own README.md with a per-file breakdown. Start there for source-level detail. See also Model Components for the per-component picture, and Model Configurations for how they're assembled into each testbench.


Building the docs site

docs/requirements.txt pins mkdocs, mkdocs-material, and this project's own vendored Pygments lexers (Sitar and SPARC assembly syntax highlighting). Set up a virtualenv once, from docs/:

python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt

Then, from docs/:

./.venv/bin/mkdocs build    # regenerates generated_site/
./.venv/bin/mkdocs serve    # live preview at http://127.0.0.1:8000

generated_site/ is committed, not gitignored. Rebuild and commit it alongside any source/ change, so it stays in sync.


Where ISA semantics live

SparcCore (model/cpp_common_code/SparcCore.cpp) is the single source of truth for instruction behavior, closely following the SPARC V8 manual with section citations throughout. Both drivers call the same methods in the same order. If you're fixing a semantics bug or adding an instruction, it belongs here, not in either driver. The fix then applies to both models automatically, and validation/asm/ runs against both (see Getting Started) and will catch a regression in either.

Where timing lives

Timing is deliberately kept out of cpp_common_code/ entirely. SparcThread.sitar and its supporting files (OpcodeLatencies.h, VirtualMainMemoryInterface.sitar, VirtualMainMemory.sitar, and, where an MMU is present, Mmu.sitar, PhysicalMainMemoryInterface.sitar, PhysicalMainMemory.sitar, and each configuration's own top-level composition file, e.g. System.sitar in core_mmu) are the only place cycle counts exist. The same holds for the later components: the caches' timing is in L1Caches.sitar, the devices' in PeripheralDevices.sitar, the buses' in SystemBridge.sitar and SystemInterconnect.sitar, and the APARA engine's in its Apara*.sitar modules. One exception: the engine's instruction latency table, and the other plain C++ helpers its pipeline stages share, are in cpp_common_code/apara/AparaTiming.h. Only the timing model uses them, the functional engine never does. See Performance Modeling.

Linking against libquadmath

FloatingPointFunctions.h needs libquadmath for quad-precision support. sitar compile --cflags only reaches the compile step (CCFLAGS), never the link step, so linking an extra library needs sitar compile's separate -l/--libs option instead. model/build_scripts/build_sitar_model.py builds with -l quadmath. If you're writing your own build script against this model instead of using it, do the same.

Test-suite conventions

See Writing and Running Assembly Programs for the full test-authoring format. A few conventions worth knowing if you're reading existing tests rather than writing new ones:

  • Every test always halts via ta 0 with traps disabled, landing the core in error_mode. This is the deliberate, universal "done" signal described on that page, not a failure indicator by itself.
  • A new configuration lists what it contains in a COMPONENTS file in its folder, and a new suite folder that needs more than the SPARC core says so in a REQUIRES file, so that validation/run_tests.py runs each suite only on the configurations that can run it (see Validation Suite).

Compatibility with the AJIT Processor

AJIT is a SPARC V8 processor developed at IIT Bombay. The models in this project serve as an approximate timing model of AJIT, for its design exploration and software development.

Some components and validation tests are adapted directly from the AJIT project, particularly the MMU, the devices, and the assembly validation suite. The core model itself is developed independently. There are several divergences between the two models and their tests. These divergences are documented in detail in docs/compliance/.