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

Adds RV32 dynamic linking using RELA with an ABI-compliant PLT/GOT and __libc_start_main, and switches .rel.plt (Arm) vs .rela.plt (RISC‑V) via ELF_MACHINE_ARM32/ELF_MACHINE_RV32. CI now builds/tests static and dynamic for arm and riscv, with new RV32 ABI tests, snapshots, and 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.
  • Architecture switch: ELF_MACHINE_* macros gate .rel.plt vs .rela.plt.
  • RISC‑V backend/ABI: internal calls direct, extern via PLT; 16‑byte stack alignment; JAL ±1 MB range check; entry via __libc_start_main; removed got_offset.
  • Build/CI: shared toolchain detection in mk/common.mk; Actions download toolchains only for dynamic jobs; matrix runs static+dynamic for arm and riscv.
  • Tests/Docs: RV32 ABI suite (tests/riscv-abi.sh), dynamic snapshots (hello, fib), expanded dynamic linking docs with RISC‑V PLT/ABI details.

• Bug Fixes

  • ABI scripts now validate exit code and output; fixed expected output for multi‑arg printf to avoid false positives.

^{Written for commit 6f43590. 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]

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]

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.
...
I will conduct this experiment on real hardware (e.g.: BeagleBone Black) later.

I have used my BeagleBone Black to conduct the same test, and the LD_PRELOAD mechanism still works on real hardware.

Demonstration:

bbb-shecc-test-ldpreload.mp4