TheRock/rocm-systems/emulation/rocjitsu/CONTRIBUTING.md

Contributing to rocjitsu

General principles

• Extend existing libraries rather than adding new ones. Check lib/util/, lib/simdojo/, and lib/rocjitsu/ before introducing a dependency or writing something from scratch.
• Follow the existing architecture. See docs/architecture.md for the component overview and where things live.
• Never manually edit autogenerated files. ISA decoders, execute bodies, legalization tables, and encoding translators are generated by the amdisa codegen pipeline. Edit the generator (lib/python/amdisa/codegen/_generator.py), regenerate, and commit all generated output. See docs/codegen.md.

Where things live

What you're adding	Where it goes
GPU hardware component (cache, queue, CU logic)	lib/rocjitsu/src/rocjitsu/vm/amdgpu/
ISA instruction semantics	lib/python/amdisa/codegen/_generator.py (regenerate)
Hand-written ISA support (address calc, matrix math)	lib/rocjitsu/src/rocjitsu/isa/arch/amdgpu/<target>/
KFD ioctl or interposer hook	lib/rocjitsu/src/rocjitsu/kmd/linux/
Binary translation rule or expansion	lib/rocjitsu/src/rocjitsu/code/dbt/
Binary instrumentation pass	lib/rocjitsu/src/rocjitsu/code/patch/
Code object loading or ELF mutation	lib/rocjitsu/src/rocjitsu/code/
Register liveness or def-use analysis	lib/rocjitsu/src/rocjitsu/analysis/
Simulation engine (events, topology, PDES)	lib/simdojo/
Shared utility (bit ops, logging, SIMD, allocators)	lib/util/
JSON config schema change	schemas/ + lib/rocjitsu/src/rocjitsu/config/
CLI changes	tools/rocjitsu/
New GPU topology config	configs/
Tests	tests/ (mirror the source structure: tests/dbt/, tests/analysis/, tests/patch/, etc.)

Libraries to use

Before writing new infrastructure, check these existing libraries:

• Logging — Use util/log.h (Logger::print<>()), never fprintf or std::cerr. Build with or without tracing via the logger's compile-time group filters.
• Bit manipulation — util/bit.h and util/bitfield.h cover masks, extraction, insertion, and typed bitfield access.
• Data types — util/data_types.h provides FP16/BF16/FP8/BF8/FP4/FP6 conversions. Extend it rather than adding ad-hoc converters.
• SIMD — util/simd.h wraps <experimental/simd> with scalar fallback. Add new SIMD primitives here, not inline in ISA execute bodies.
• Intrusive list — util/intrusive_list.h for linked data structures that need O(1) insert/erase without heap allocation per node.
• Arena allocator — util/arena_alloc.h for fixed-size block pools.
• Exceptions — util/except.h for InvalidInst, UnimplementedInst, ConfigError.
• Register sets — isa/register_set.h for ISA-independent register file modeling (SGPR/VGPR/AccVGPR bitsets).
• Spill manager — code/patch/spill_manager.h for scratch layout planning (DBI spill/fill slots).
• Instruction builder — code/patch/instruction_builder.h for encoding common instructions (s_branch, s_nop, etc.).

Code style

• C++20. Use standard library features (concepts, ranges, std::format).
• Formatting. The repo uses pre-commit hooks (clang-format for C++, black for Python, gersemi for CMake). Install once and run before every commit:

  pip install pre-commit
  pre-commit install
  pre-commit run --all-files
  

  The config lives at the repo root (rocm-systems/.pre-commit-config.yaml).
• Naming. Use clear, descriptive names. No single-letter variables. Non-trivial types with methods must be class (not struct). Maintain public: / protected: / private: ordering.
• Comments. Use @brief / @details doxygen style when documenting public APIs. Avoid decorative comment lines (---, ===). Default to writing no comments; only comment when the why is non-obvious.
• No fprintf. Always use Logger from util/log.h.
• Exceptions. Exceptions are used only for unrecoverable errors during initialization and configuration (ConfigError) or when encountering invalid/unimplemented instructions during code object parsing (InvalidInst, UnimplementedInst). All exception types live in util/except.h. Do not throw exceptions in simulation hot paths (event handlers, instruction execution, cache lookups). Do not add try/catch blocks unless you are at a boundary that must translate an error (e.g., the C API layer). There is no general exception safety guarantee — assume code is not exception-safe unless explicitly documented.

ISA codegen workflow

When modifying instruction semantics or adding instruction support:

1. Edit lib/python/amdisa/codegen/_generator.py (never the generated C++ files)
2. Regenerate with --multi mode (see docs/codegen.md)
3. Format the generated files with clang-format
4. Stage ALL generated files before committing

Testing

• Add tests for new functionality. Place them in tests/ mirroring the source directory structure.
• Run the test suite: ctest --test-dir build
• Run Python tests: cd lib/python && python -m pytest amdisa/tests/ -x
• Ensure zero compiler warnings before submitting.

Proposing architectural changes

Large changes that affect the component structure, add new subsystems, change public APIs, or modify the translation/instrumentation pipeline must be proposed before implementation. Open a GitHub issue with:

• A clear title describing the proposed change
• A markdown document (attached or inline) covering:
  • Motivation — What problem does this solve and why now?
  • Design — Proposed architecture, component interactions, data flow
  • Alternatives considered — What else was evaluated and why it was rejected
  • Migration / compatibility — Impact on existing code, tests, and users
  • Scope — What is and is not included in the change

Wait for maintainer review and approval before starting implementation. This avoids wasted effort on changes that conflict with the project direction or duplicate ongoing work.

Examples of changes that require a proposal:

• Adding a new translation pair or instrumentation pass
• Changing the KFD ioctl interface or RPC protocol
• Restructuring the simulation engine or cache hierarchy
• Introducing new external dependencies

Bug fixes, test additions, and localized improvements do not need a proposal — open a PR directly.

Commit hygiene

• Never commit buggy or untested code. Verify end-to-end first.
• Write concise commit messages focused on the why, not the what.
• When regenerating ISA files, include all generated output in the same commit as the generator change.