mRL78

mRL78 is a C++20 scaffold for an RL78 emulator. The first milestone targets an RL78/G13-style RL78-S2 CPU core with ELF and Intel HEX loading.

🚀 Quick Start

vcpkg is available on this machine at /usr/bin/vcpkg, but CMake still needs a vcpkg root that contains scripts/buildsystems/vcpkg.cmake.

git submodule update --init --recursive
export VCPKG_ROOT=/path/to/vcpkg
cmake --preset llvm_debug
cmake --build --preset llvm_debug
ctest --preset llvm_debug

If you prefer passing the vcpkg toolchain directly:

cmake -S . -B build/llvm_debug \
  -G Ninja \
  -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake \
  -DVCPKG_TARGET_TRIPLET=x64-linux \
  -DVCPKG_OVERLAY_TRIPLETS=cmake/triplets
cmake --build build/llvm_debug
ctest --test-dir build/llvm_debug --output-on-failure

🛠️ Build Requirements

Observed local tools:

Tool	Version
CMake	4.3.3
Ninja	1.13.2
clang++	22.1.6
ld.lld	22.1.6
vcpkg	2026-05-27-d5b6777d666efc1a7f491babfcdab37794c1ae3e

Available presets:

Preset	Purpose
llvm_debug	Debug build with clang/libc++/lld-oriented triplet
llvm_release	Release build
asan	AddressSanitizer build
ubsan	UndefinedBehaviorSanitizer build
fuzz	Placeholder preset for compiler-rt/libFuzzer targets

🧪 Testing

cmake --preset llvm_debug
cmake --build --preset llvm_debug
ctest --preset llvm_debug

The first scaffold tests cover address validation, flat memory bus behavior, CPU reset, unsupported opcode traps, and simple Intel HEX loading.

🔁 CI/CD

GitHub Actions runs CI on Git Flow branches and pull requests targeting main or develop. CI checks llvm_debug, asan, and ubsan, initializes submodules, uses vcpkg manifest mode, and verifies compile_commands.json.

Release artifact packaging runs only for version tags such as v0.1.0. It builds llvm_release and uploads a Linux x64 tarball as a workflow artifact.

See docs/ci_cd.md for workflow triggers, release artifact rules, and local equivalents. Because this repository is private, workflow badges are intended for authenticated GitHub viewers.

🧪 Real Firmware Testing

Real firmware testing is staged because the CPU core does not yet execute the full RL78 instruction set. The project supports loader/trap testing first, then execution tests as instruction coverage grows.

Self-authored RL78/G13 fixtures can be built when rl78-elf-gcc, rl78-elf-objcopy, and rl78-elf-objdump are installed:

cmake --preset llvm_debug -DMRL78_ENABLE_FIRMWARE_FIXTURES=ON
cmake --build --preset llvm_debug --target mrl78_firmware_fixtures
ctest --preset llvm_debug -L firmware

External firmware corpora are supported as local-only inputs:

cmake --preset llvm_debug \
  -DMRL78_ENABLE_EXTERNAL_FIRMWARE_CORPUS=ON \
  -DMRL78_FIRMWARE_CORPUS_DIR=/path/to/rl78/firmware/corpus
ctest --preset llvm_debug -L external_firmware

See docs/testing_real_firmware.md for fixture design, toolchain setup, licensing cautions, and candidate firmware sources.

🧱 Architecture

The project uses namespace-module style instead of subsystem classes:

• behavior lives in free functions inside namespaces;
• state and data live in plain snake_case structs;
• headers do not use using namespace;
• classes are reserved for narrow RAII wrappers or test helpers.

Primary namespaces:

Namespace	Responsibility
mrl78::support	Shared primitive types and validation
mrl78::memory	Flat memory and bus function table
mrl78::decode	Instruction decoding
mrl78::core	CPU state and execution
mrl78::loader	ELF and Intel HEX program loading
mrl78::cli	Command-line integration

📦 Dependencies

Dependencies are managed by vcpkg manifest mode:

• cli11
• fmt
• gtest

ELFIO is vendored as a Git submodule at external/elfio because it is not available through the active vcpkg registry.

After cloning this repository, initialize submodules with:

git submodule update --init --recursive

Intel HEX parsing is implemented in-tree because the required v1 format support is small and benefits from emulator-specific validation.

🎯 Scope

Included in v1:

• RL78/G13-oriented RL78-S2 CPU scaffold;
• 20-bit address validation and 1 MiB flat memory;
• CPU reset and unsupported opcode traps;
• ELF and Intel HEX loader APIs;
• CLI commands: run, disasm, and dump_image.

Deferred:

• board models;
• timers and serial I/O;
• peripheral emulation;
• complete interrupt controller behavior;
• complete RL78 instruction execution;
• S3-only instruction behavior.

⚖️ License

This project is licensed under GPL-3.0-only. See LICENSE.

📚 References

• RL78 software manual: https://www.renesas.com/en/document/mah/rl78-family-users-manual-software-rev230
• RL78/G13 hardware manual: https://www.renesas.com/en/document/man/rl78g13-users-manual-hardware
• GNU GPL v3: https://www.gnu.org/licenses/gpl-3.0.en.html
• vcpkg manifest mode: https://learn.microsoft.com/en-us/vcpkg/concepts/manifest-mode
• vcpkg CMake integration: https://learn.microsoft.com/en-us/vcpkg/users/buildsystems/cmake-integration
• LLVM CMake runtime options: https://llvm.org/docs/CMake.html
• Clang toolchain runtime docs: https://clang.llvm.org/docs/Toolchain.html
• GoogleTest CMake quickstart: https://google.github.io/googletest/quickstart-cmake.html
• CMake Presets docs: https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html
• GCC RL78 target options: https://gcc.gnu.org/onlinedocs/gcc/RL78-Options.html
• Hirakuni45 RL78 samples: https://github.com/hirakuni45/RL78
• Renesas IoT reference for RL78: https://github.com/renesas/iot-reference-rl78
• GDB RL78 simulator source: https://sources.debian.org/src/gdb/10.1-2/sim/rl78/rl78.c