relcc2

A research project on compiling for Elbrus (E2K), MCST's VLIW architecture. It has two parts:

• A specification of the E2K ISA and ABI (spec/), written for anyone who compiles, emulates, debugs or JITs for E2K. Its facts come from MCST's public documentation and GPL sources, and are checked against the hardware and against MCST's compiler.
• A proof-of-concept GCC backend built from that specification, in a separate repository: OpenE2K/gcc-claude, branch claudes-e2k-compiler.

"RE" stands for research and "L" for Elbrus, as in MCST's compiler lcc. The project decompiles nothing (see "Clean sources" below).

How this was made

Nearly all of this repository and all of the GCC backend were written by Claude, Anthropic's AI model, at the owner's request and under the owner's direction. The owner set the goals, the sources and the rules below, provided the hardware and reviewed the results. The commits here carry the owner's name; their messages link the agent sessions that wrote them.

The specification is not taken on the model's word. Every ABI rule carries its source and every ISA section its verification status, and facts measured on hardware name the probe that settled them and the machines it ran on: an Elbrus-4C (v3), an Elbrus-8C2 (v5) and an Elbrus-2C3 (v6). Read it as research notes checked by experiment, written in the hope that they will be useful.

The GCC backend is not for upstream

The backend is research material. It exists to find what the specification gets wrong or leaves out, and it did. It is heavily AI-written, and GCC does not accept AI-generated contributions, so nothing from it is meant for upstream GCC. In the owner's words: "you can bite me if I send anything from it to upstream."

What it has done so far:

• ABI compatibility. It passes the compat suite (tools/abi/compat) in both directions against lcc's code on all three machines: 1,931 tests per pair of compilers, covering calls, varargs, longjmp and C++ exceptions.
• GCC built by itself. A native GCC that the backend built reproduces its cross compiler's output byte for byte for all 2,578 compiles of a GCC build (tools/gcc-replay).
• A system with nothing from lcc. MCST's Linux and glibc, binutils, gdb, GCC and busybox, all compiled by it, boot on the 8C2 (tools/distro).
• OS Elbrus's packages. It has built 2,563 of the 2,640 source packages of OS Elbrus 9.5.5 from MCST's package kit (that work is not in this repository).

Its own README and gcc/config/e2k/STATUS.claude.md cover its design, results and how to build it.

The specification

Where	What
spec/isa/	Wide-instruction format and encodings, every operation (v2 to v7), what operations compute, latencies and hazards measured per CPU, branches and calls, predicates, loop mode and array prefetch, speculation, performance monitors, hardware errata
spec/abi/	The 64-bit (e2k64) ABI: data layout, registers and DWARF numbers, the calling convention and C++ ABI, stacks and unwinding, ELF, PIC and TLS, atomics, the kernel interface, what building MCST's Linux and glibc asks of a compiler, lcc's builtins and source extensions
spec/abi/mode32.md, protected-mode.md	32-bit and protected (e2k128) modes, for completeness
spec/**/*.yaml	Machine-readable data, generated by tools/ (each file names its source revision)
doc/gcc-port-plan.md	A plan for writing a GCC port by hand against the specification

Every ABI rule is marked with its source (spec/abi/README.md defines the marks), and every ISA section with how far it is verified ([hw], [checked], [source], ...). v4 is not measured, and v7 (not in silicon) comes only from binutils, the kernel and the community QEMU.

Tools

Where	What
tools/isa-extract/	Generates the ISA data from MCST's binutils and checks it against gas
tools/isa-decode/	A decoder written from the specification alone, compared with objdump
tools/isa-probes/, tools/abi/probes/	Small programs that settle one question each, on hardware or by reading a compiler's output
tools/isa-timing/, tools/isa-score/	Latency and throughput measurements; a static schedule model checked against the machines
tools/abi/compat/	The ABI compatibility suite: caller and callee from different compilers, run under QEMU or on hardware
tools/abi/builtins/	lcc's __builtin_e2k_* compared builtin by builtin
tools/dejagnu/	Boards for running GCC's testsuite under QEMU or on the machines
tools/gcc-native/, tools/gcc-replay/, tools/quadmath/, tools/distro/	Building and checking the GCC backend: native builds, the replay check, libquadmath, a bootable system

AGENTS.md is the guide written for the AI agents working here. It is also the most detailed account of the project's state and of the traps met along the way.

Clean sources

• Facts come from openly licensed material:
  • MCST's programming guide "Руководство по эффективному программированию на платформе «Эльбрус»" (CC BY 4.0);
  • MCST's GPL ports of binutils, gdb, glibc, Linux and the GCC runtime libraries;
  • MCST's and the community's QEMU;
  • lcc's user manual, which MCST ships with the compiler.
• Proprietary compilers (lcc, Unipro's LLVM) are used only as black boxes: we compile probes and read their output. Their code is never decompiled or copied here.
• Leaked or unpublished MCST material is never used.

The reference sources are git submodules (git submodule update --init):

OpenE2K/binutils-gdb          MCST binutils 2.41    github.com/OpenE2K/binutils-gdb
OpenE2K/gdb                   MCST gdb 15.2         same repository, gdb-15.2-mcst branch
OpenE2K/glibc                 MCST glibc 2.35       github.com/OpenE2K/glibc
OpenE2K/linux                 MCST Linux 6.1        github.com/OpenE2K/linux
OpenE2K/qemu-e2k-community    community QEMU e2k    github.com/OpenE2K/qemu-e2k
OpenE2K/qemu-e2k-mcst         MCST QEMU e2k         git.openelbrus.ru/mcst/qemu

Toolchains

The scripts in tools/setup/ install the reference toolchains into toolchains/ (untracked), where the tools look for them.

Script	Installs
setup-unipro.sh [DEB_DIR]	Unipro's LLVM 20 with the Elbrus target, from the x86_64 debs in x86_64/, as toolchains/unipro/bin/{clang,llc,…}
build-binutils.sh	MCST binutils built from OpenE2K/binutils-gdb, in toolchains/binutils/bin/e2k-linux-*
fetch-lcc.sh [VERSION] [TARGET]	MCST lcc cross compiler (default 1.29.16, e2k-v5) from the archive at https://setwd.ws/sp, as toolchains/lcc-VERSION-TARGET/{lcc,l++,ldis}. It needs bwrap
build-qemu.sh [mcst|community]	qemu-e2k Linux user mode built from both QEMU submodules, as toolchains/qemu-{mcst,community}/bin/qemu-e2k
fetch-lcc-libs.sh	MCST's GPL GCC runtime libraries and libffi sources, in toolchains/src/

lcc includes a sysroot, so it can link complete programs for E2K. The checks that must pass are listed in AGENTS.md ("Checks").

Licence

• spec/ is licensed under CC BY-SA 4.0; it adapts MCST's CC BY 4.0 programming guide. See spec/NOTICE.md.
• Everything else in this repository (the tools) is licensed under the GNU General Public License, version 3 or later. See COPYING.
• The submodules under OpenE2K/ keep their own licences.
• The GCC backend is part of a GCC tree and under GCC's licences.