Implement RISC-V dynamic linking

[DrXiao]

The proposed changes primarily improve the ELF generation and the RISC-V backend, enabling the build system to generate a dynamically linked shecc targeting the RISC-V architecture.

Although the current changes allow both bootstrapping and test suite to complete successfully, this is still a work in progress. The TODO items are listed as follows:

• Enhance code quality, comments and commit messages.
• Confirm the RISC-V ABI compliance.
• Add a new script (riscv-abi.sh) to validate the RISC-V ABI.
• Improve the documentation and README.
• Consolidate arm.mk and riscv.mk into a common build logic (e.g.: configure RUNNER_LD_PREFIX).

---

Summary by cubic

Implements RV32 dynamic linking using RELA with an ABI‑compliant PLT/GOT and __libc_start_main, and switches REL (Arm) vs RELA (RISC‑V) via ELF_MACHINE_ARM32/ELF_MACHINE_RV32. CI now builds/tests static and dynamic for arm and riscv, adds an RV32 ABI suite, and updates docs.

• New Features

  • RISC‑V dynamic linking: .rela.plt; PLT0=32B, stubs=16B; RESERVED_GOT_NUM (RV32=2, ARM=3); DYN_LINKER /lib/ld-linux-riscv32-ilp32d.so.1; ELF_FLAGS 0x4; correct DT_RELA*/DT_REL*, DT_PLTREL, DT_PLTRELSZ, DT_JMPREL.
  • RISC‑V backend/ABI: internal calls direct, extern via PLT; entry via __libc_start_main; 16‑byte stack alignment; JAL ±1MB range check.
  • ELF/Codegen: arch‑driven .rel.plt vs .rela.plt via use_relaplt; ELF_MACHINE_* macros used across code; improved GOT/PLT generation; removed unused got_offset from struct func.
  • Tests/Docs: RV32 ABI suite (tests/riscv-abi.sh); dynamic snapshots (hello, fib); expanded dynamic linking docs incl. RISC‑V PLT/ABI details.

• Dependencies

  • Build/CI: shared toolchain detection in mk/common.mk with per‑arch candidates and auto RUNNER_LD_PREFIX; GitHub Actions downloads a riscv32 glibc toolchain only for dynamic runs; matrix runs static+dynamic for arm and riscv.

^{Written for commit ea51c76. Summary will update on new commits.}

[DrXiao]

As the apt package manager only provides a 64-bit RISC-V GNU cross-compilation toolchain, I utilize riscv-gnu-toolchain , which is a 32-bit variant, and leverage its artifacts for RISC-V dynamic linking development and validation.

The updated GitHub Actions also downloads the 32-bit variant to validate RISC-V dynamic linking.

[jserv]

As the apt package manager only provides a 64-bit RISC-V GNU cross-compilation toolchain, I utilize riscv-gnu-toolchain , which is a 32-bit variant, and leverage its artifacts for RISC-V dynamic linking development and validation.
The updated GitHub Actions also downloads the 32-bit variant to validate RISC-V dynamic linking.

Evaluate Run 32-bit applications on 64-bit Linux kernel, which is exactly RV32-on-RV64 userspace compatibility, not emulation.

[DrXiao]

Evaluate Run 32-bit applications on 64-bit Linux kernel, which is exactly RV32-on-RV64 userspace compatibility, not emulation.

I'm not sure whether I understand correctly. Do you mean that the proposed changes should be verified on a RISC-V machine?

[jserv]

Do you mean that the proposed changes should be verified on a RISC-V machine?

See sysprog21/kbox#18
The RISE RISC-V Runners is a managed GitHub Actions runner service that executes CI/CD workflows on real RISC-V hardware.

[DrXiao]

RISE RISC-V Runners' documentation explicitly states that binaries must be compiled for riscv64. According to the FAQ - What architectures are supported?.

RISC-V 64-bit (riscv64) only. All runners execute on physical RISC-V hardware. There is no RISC-V emulation. Binaries must be compiled for riscv64.

I created another branch (feat/dynlink-for-rv32-test-rv64-runner) to verify if these RISC-V runners could support riscv32 binaries. However, the test result indicates that the runner failed to execute statically linked shecc.

Based on both the documentation and my test, it appears that RISE RISC-V runners lack support for 32-bit executables.

[DrXiao]

RISC-V calling convention:

1. First eight arguments are passed to a0-a7, and the extra arguments are pushed onto the stack.
2. stack should be 128-bit (16-byte) aligned. In RISC-V ABIs Specification document, the section 2-1 describes

   2-1. Integer Calling Convention

   The stack grows downwards (towards lower addresses) and the stack pointer shall be aligned to a
   128-bit boundary upon procedure entry.

3. Caller/Callee saved registers:

   Register ABI Name	Saver
   zero, gp, tp	(None)
   ra	Caller
   sp	Callee
   a0 - a7	Caller
   s0 - s11	Callee
   t0 - t6	Caller

---

Item 1: is done by the register allocation phase.

The register allocator uses virtual registers (vreg0-vreg7) to allocate reigsters for arguments when encountering a function call. vreg0-vreg7 will be mapped to a0-a7, so first eight arguments are naturally passed to these registers.

Since the current shecc only supports up to 8 arguments, no extra arguments need to be passed to the stack. Thus, we can skip this handling.

Item 2: is ensured by the RISC-V code generator.

When handling the stack pointer, the code generator will guarantee that sp is always incremented or decremented by a multiple of 16 bytes.

Item 3:

• ra and sp: are properly handled by the code generator.
• a0 - a7: are implicitly handled in register allocation phase.
• s0 - s11: are not necessary to be preserved or restored.
• t0 - t6: are not necessary to be handled.

Therefore, this item can also be considered complete. Further details and explanations can be found in riscv-codegen.c.

[DrXiao]

Since there may be additional requirements to address, I am still keeping this pull request as a draft currently, and will continue to make improvements if necessary.

[DrXiao]

About LD_PRELOAD

The LD_PRELOAD mechanism allows specified libraries to be loaded before any other shared libraries (e.g.: libc.so) required by the running process, and the process can call a "wrapper" function.

This raises an interesting question: whether the dynamically linked executables generated by shecc can utilize LD_PRELOAD to perform "function interposition'.

Therefore, I prepared the following code and conducted an experiment, and it is pleasing that the generated executables can indeed leverage LD_PRELOAD and execute successfully.

Test library

The 'wrapped' malloc() can allocate memory and print the allocated size to standard output.

#include <stddef.h>
#include <string.h>
#include <stdio.h>
#include <dlfcn.h>
#include <unistd.h>
void *malloc(size_t size) {
    char buf[32];
    static void *(*real_malloc)(size_t) = NULL;
    if (real_malloc == NULL) {
        real_malloc = dlsym(RTLD_NEXT, "malloc");
    }
    sprintf(buf, "malloc called, size = %zu\n", size);
    write(2, buf, strlen(buf));
    return real_malloc(size);
}

Use arm-linux-gnueabihf-gcc to build libmcount.so for later use.

$ arm-linux-gnueabihf-gcc -D_GNU_SOURCE -shared -ldl -fPIC -o libmcount.so malloc_count.c

Test program

/* test.c */
int main()
{
    int *a[3];

    a[0] = malloc(sizeof(int));
    a[1] = malloc(sizeof(int) * 7);
    a[2] = malloc(sizeof(int) * 1024);

    free(a[0]);
    free(a[1]);
    free(a[2]);

    return 0;
}

Use shecc to compile a dynamically linked executable, and then run it in QEMU with LD_PRELOAD=./libmcount.so.

$ make DYNLINK=1
$ qemu-arm -L /usr/arm-linux-gnueabihf/ out/shecc-stage2.elf --dynlink -o test test.c
$ qemu-arm -L /usr/arm-linux-gnueabihf/ -E LD_PRELOAD=./libmcount.so ./test
malloc called, size = 4
malloc called, size = 28
malloc called, size = 4096

We can observe that test.c calls the wrapped malloc() three times. Each call successfully allocates memory and correctly prints the allocated size.

---

Function interposition is also supported on the RISC-V architecture:

$ riscv32-unknown-linux-gnu-gcc -D_GNU_SOURCE -shared -ldl -fPIC -o libmcount.so malloc_count.c
$ make DYNLINK=1 ARCH=riscv
$ qemu-riscv32 -L $(riscv32-unknown-linux-gnu-gcc --print-sysroot) out/shecc-stage2.elf --dynlink -o test test.c
$ qemu-riscv32 -L $(riscv32-unknown-linux-gnu-gcc --print-sysroot) -E LD_PRELOAD=./libmcount.so ./test
malloc called, size = 4
malloc called, size = 28
malloc called, size = 4096

---

I will conduct this experiment on real hardware (e.g.: BeagleBone Black) later.

[jserv]

Review notes on the RV32 dynamic linking implementation. Findings are inlined at their locations.

[jserv]

This jal to PLT[1] (and the extern calls at OP_call / OP_address_of_func) spans .text + .rodata + .rel(a).plt to reach .plt, so the offset is roughly code_size + rodata_size. rv_encode_J in src/riscv.c has no range check, unlike rv_encode_I/S/B which all fatal() on overflow. Past the J-type reach of ±1 MB the high bits are silently dropped and the jump lands at the wrong address, a silent miscompile the small hello/fib tests never approach. Add the same guard to rv_encode_J: if (imm > 1048575 || imm < -1048576) fatal("Offset too large"); (src/riscv.c is not part of this PR, so this comment is anchored on the call site.)

[jserv]

The interpreter is ld-linux-riscv32-ilp32d.so.1 (double-float ABI) while ELF_FLAGS remains 0, which declares soft-float. The object's e_flags should carry EF_RISCV_FLOAT_ABI_DOUBLE (0x4) to match the ilp32d loader, or the target should select an ILP32 soft-float linker/toolchain. As written the ABI tag contradicts the chosen interpreter and may be rejected or misinterpreted by strict tools.

[jserv]

GOT init relies on implicit ELF_MACHINE_ARM32 -> ELF_MACHINE_RV32 case fallthrough. It is correct for both arches (ARM writes GOT[0]=&.dynamic then two zeros; RV32 writes two zeros), but it emits -Wimplicit-fallthrough, and a stray break or a case reorder would silently corrupt ARM GOT init with no failure on the RV32 CI leg. Add a /* fall through */ annotation, or write the shared zero entries explicitly per case.

[jserv]

A test is counted as passed on exit_code == 0 alone; an expected_output mismatch is only a warning, and only under VERBOSE. A broken external-call path that still exits 0 passes silently, which is exactly the failure mode this suite is meant to catch. Treat a non-matching expected_output as a failure.

[DrXiao]

Currently, s0 and s1 may be used under dynamic linking. I will update the above descriptions.