GNU binutils and GDB backend

Seal5 can generate a unified patch for GNU GAS, ld, objdump and GDB’s shared RISC-V disassembler. This lets the GNU tools assemble custom mnemonics, retain custom ISA attributes when linking LLVM-produced objects, and display the same mnemonics in objdump and GDB. No GCC or C library rebuild is needed.

Generate the patch

First run the normal Seal5 transform pipeline. The backend consumes its .seal5/models/*.seal5model files, after register and immediate operand collection. Generate against the unpatched source checkout you will build; source files are read but never modified by the generator:

source venv310/bin/activate
python -m seal5.backends.riscv_gnu.writer \
  /tmp/seal5_llvm_demo_llvm23/.seal5/models/Example.seal5model \
  /tmp/seal5_llvm_demo_llvm23/.seal5/models/XCoreVNand.seal5model \
  --source /path/to/binutils-gdb \
  --output /tmp/seal5-gnu.patch

Pass all the models together to produce one patch. A sibling /tmp/seal5-gnu.json lists the generated instructions and extension names. The patch is relative to the binutils/GDB source root, not the Seal5 root. Already-patched checkouts and unfamiliar source layouts are rejected.

To enable the backend during seal5 generate, set SEAL5_GNU_SOURCE=/path/to/binutils-gdb. Alternatively add a configuration:

passes:
  overrides:
    riscv_gnu:
      source: /path/to/binutils-gdb

The flow writes .seal5/patches/binutils-gdb/seal5.patch and seal5.json. Generation is disabled when no source is configured. GNU patches are applied separately from Seal5’s LLVM patch stages.

Using riscv-gnu-toolchain

If using a riscv-gnu-toolchain checkout, initialize its binutils submodule and use that directory as --source. Generate and apply a separate patch against its gdb submodule if GDB comes from a different checkout/revision. Each contains the shared binutils/GDB source tree; a patch generated for one revision should not be assumed to apply to the other:

cd /path/to/riscv-gnu-toolchain
git submodule update --init --depth 1 binutils
# Optional, for the debugger:
git submodule update --init --depth 1 gdb

Apply the generated patch from the source root:

cd /path/to/binutils-gdb
git apply --check /tmp/seal5-gnu.patch
git apply /tmp/seal5-gnu.patch

To regenerate, first reverse the old patch with git apply -R /tmp/seal5-gnu.patch or use a fresh checkout. Save the old patch until it has been reversed.

Fast build: assembler, linker and objdump

Use a separate build directory. A native C/C++ compiler, make, flex, bison, texinfo and the normal binutils development dependencies are needed. On Debian or Ubuntu, build-essential flex bison texinfo libgmp-dev libmpfr-dev cover the core prerequisites. The following builds just the required cross tools, without GCC, newlib, Linux, or a target sysroot:

mkdir -p /tmp/seal5-gnu-build
cd /tmp/seal5-gnu-build
/path/to/binutils-gdb/configure \
  --target=riscv64-unknown-elf \
  --prefix="$HOME/.local/seal5-gnu" \
  --disable-werror --disable-nls --disable-sim --disable-gprofng \
  --without-debuginfod --without-python --without-guile
make -j8 all-gas all-binutils all-ld

These tools support both RV32 and RV64 ELF. Select RV32 at assembly/link time, not by rebuilding. Reduce -j8 if memory is limited. Named make targets avoid the much larger top-level riscv-gnu-toolchain build. The tools can be used directly from the build tree:

gas/as-new --version
ld/ld-new --version
binutils/objdump --version

Optionally install just these components:

make install-gas install-binutils install-ld

Installed names have the riscv64-unknown-elf- prefix, even when processing RV32 code.

Optional GDB

With a patched combined source tree and the configuration above:

make -j8 all-gdb
gdb/gdb --version
# Optional:
make install-gdb

GDB is a host program and needs a C++17-capable compiler. GNU GMP and MPFR headers/libraries are also required. Python, Guile, debuginfod and the simulator are disabled above to reduce build dependencies. GDB is optional for the fast binutils build; its disassembler uses the same generated opcode support.

If the toolchain’s GDB submodule differs from its binutils submodule, use a second build directory configured against the separately patched GDB checkout, then run make -j8 all-gdb there.

Smoke test with the Seal5 demo

After generating the patch from both demo models, create /tmp/custom.s:

.attribute arch, "rv32i2p1_xcorevnand1p0_xexample1p0"
.text
.global _start
_start:
  cv.nand.bitwise a0, a1, a2
  xexample.subincacc a0, a1, a2
  xexample.slli_add_addi a0, a1, a2, -4, 31

Run from the GNU build directory:

gas/as-new -march=rv32i_xcorevnand_xexample -o /tmp/custom.o /tmp/custom.s
ld/ld-new -m elf32lriscv -e _start -Ttext=0x1000 \
  -o /tmp/custom.elf /tmp/custom.o
binutils/objdump -d /tmp/custom.elf
gdb/gdb -nx -batch /tmp/custom.elf \
  -ex 'disassemble /r _start,_start+12'

Both decoders should display all three custom mnemonics. The last instruction uses nonstandard register positions, two immediate fields and a negative immediate; its encoding is 9f62d457.

LLVM-generated objects work directly with these tools. For example:

demo=/tmp/seal5_llvm_demo_llvm23/.seal5/tests/Output
ld/ld-new -m elf32lriscv -r -o /tmp/custom-linked.o \
  "$demo/cv-nand-bitwise.test-inline-asm.c.tmp.o" \
  "$demo/xexample-subincacc.test-inline-asm.c.tmp.o"
binutils/readelf -A /tmp/custom-linked.o
binutils/objdump -d /tmp/custom-linked.o

readelf should show both xcorevnand1p0 and xexample1p0 in the merged architecture attribute. This verifies that the linker accepts and merges the custom extensions, rather than just preserving unknown instruction bytes.

The same demo checks can be repeated automatically from the Seal5 repository:

source venv310/bin/activate
python scripts/test_riscv_gnu.py --build /tmp/seal5-gnu-build \
  --gdb /tmp/seal5-gnu-build/gdb/gdb \
  --llvm-demo /tmp/seal5_llvm_demo_llvm23

Omit --gdb or --llvm-demo when those optional checks are unavailable. The script also checks instruction words, immediate range errors and rejection of custom mnemonics when the required extension is disabled.

Scope and source compatibility

The backend emits fixed-bit opcode matches, arbitrary split operand fields, GPR/FPR operands, compressed GPR indices, numeric or named CSR operands, signed/unsigned constant immediates, and vendor extension version registrations. It uses existing RISC-V ELF relocations and does not add relocation types for custom symbolic immediate operands. Custom immediate arguments to GAS must currently be assembly-time constants. Hardware execution and GDB simulation of instruction semantics are outside opcode/disassembler support.

The generator checks the expected upstream source anchors and adapts to old and current libopcodes printing and GAS expression interfaces. An upstream source-layout change may require a generator update; generation fails instead of silently leaving out a component. Current upstream binutils/GDB commit 17d606a601f4957f9591b2bfb3f39b57716e531d was used for the initial complete GAS/ld/objdump/GDB build and demo smoke test.