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).
• (Any new requirements ...)

---

Summary by cubic

Implements RV32 dynamic linking using RELA with an ABI‑compliant PLT/GOT and a __libc_start_main entry, and adds ELF_MACHINE_ARM32/ELF_MACHINE_RV32 to drive REL (Arm) vs RELA (RISC‑V). CI now validates static and dynamic builds for both arm and riscv, and a new ABI suite checks RV32 calling, stack, and external call behavior.

• New Features

  • RV32 dynamic linking: .rela.plt; PLT0=32B, stubs=16B; per‑arch RESERVED_GOT_NUM (RV32=2, ARM=3); DYN_LINKER /lib/ld-linux-riscv32-ilp32d.so.1; .got init honors reserved entries; correct dynamic tags for RELA/REL (DT_RELA*, DT_REL*, DT_PLTREL, DT_PLTRELSZ, DT_JMPREL).
  • RISC‑V backend: ABI‑compliant PLT generation; internal calls direct, externs via PLT; entry calls __libc_start_main and returns via saved ra; syscall trampoline retained for static; 16‑byte stack alignment.
  • Tests/CI: RISC‑V ABI suite (parameter passing, stack alignment, return values, register preservation, structure passing, external calls); RV32 dynamic snapshots (hello, fib); GitHub Actions runs static+dynamic for arm and riscv.
  • Docs: dynamic linking guide expanded for Arm/RISC‑V (stack/call conventions, RISC‑V PLT, runtime flow, interpreter paths).

• Dependencies

  • Consolidated toolchain detection in mk/common.mk with per‑arch TOOLCHAIN_CANDIDATES and auto RUNNER_LD_PREFIX; CI installs a riscv32 glibc toolchain and exports /opt/riscv/bin to PATH.

^{Written for commit 14220c1. 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.

[cubic-dev-ai]

4 issues found across 15 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".github/workflows/main.yml">

<violation number="1" location=".github/workflows/main.yml:23">
P2: The riscv32 glibc toolchain is downloaded and extracted on every matrix entry, including architecture: arm builds where it's never used. Wrap lines 23-25 with `if: matrix.architecture == 'riscv'` to avoid unnecessary download time (~minutes) and disk usage on ARM CI runs.</violation>
</file>

<file name="src/riscv-codegen.c">

<violation number="1" location="src/riscv-codegen.c:662">
P2: Programs whose global initialization clobbers `t1` or `t2` pass corrupted `argc`/`argv` to `main`. Preserve these values in memory or saved registers across `GLOBAL_FUNC`, restoring them before the main call.</violation>
</file>

<file name="mk/common.mk">

<violation number="1" location="mk/common.mk:46">
P2: Dynamic runs can use the developer’s home directory as qemu’s sysroot when the selected cross compiler has no configured sysroot. Treat an empty `--print-sysroot` result like `/` so the existing target-prefix fallback locates the loader.</violation>
</file>

<file name="docs/dynamic-linking.md">

<violation number="1" location="docs/dynamic-linking.md:281">
P3: The formula `N * 4` for the N-th function's GOT offset is inconsistent with the GOT[2] → offset 0 entry. If 1st function is offset 0, then N-th function offset should be (N-1)*4. Or if GOT[2] is at offset 8, then N-th function offset is (N+1)*4. Either way the table and formula contradict each other.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The riscv32 glibc toolchain is downloaded and extracted on every matrix entry, including architecture: arm builds where it's never used. Wrap lines 23-25 with if: matrix.architecture == 'riscv' to avoid unnecessary download time (~minutes) and disk usage on ARM CI runs.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .github/workflows/main.yml, line 23:

<comment>The riscv32 glibc toolchain is downloaded and extracted on every matrix entry, including architecture: arm builds where it's never used. Wrap lines 23-25 with `if: matrix.architecture == 'riscv'` to avoid unnecessary download time (~minutes) and disk usage on ARM CI runs.</comment>

<file context>
@@ -27,6 +20,9 @@ jobs:
           sudo apt-get install -q -y qemu-user
           sudo apt-get install -q -y build-essential
           sudo apt-get install -q -y gcc-arm-linux-gnueabihf
+          sudo wget -q https://github.com/riscv-collab/riscv-gnu-toolchain/releases/download/2026.07.15/riscv32-glibc-ubuntu-24.04-gcc.tar.xz
+          sudo tar Jxf riscv32-glibc-ubuntu-24.04-gcc.tar.xz -C /opt
+          echo "/opt/riscv/bin" >> "$GITHUB_PATH"
</file context>

[cubic-dev-ai]

P2: Programs whose global initialization clobbers t1 or t2 pass corrupted argc/argv to main. Preserve these values in memory or saved registers across GLOBAL_FUNC, restoring them before the main call.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/riscv-codegen.c, line 662:

<comment>Programs whose global initialization clobbers `t1` or `t2` pass corrupted `argc`/`argv` to `main`. Preserve these values in memory or saved registers across `GLOBAL_FUNC`, restoring them before the main call.</comment>

<file context>
@@ -482,47 +601,273 @@ void emit_ph2_ir(ph2_ir_t *ph2_ir)
+         * After the main function completes its execution, it must use
+         * the content of ra to transfer control back to __libc_start_main().
+         */
+        emit(__addi(__t1, __a0, 0));
+        emit(__addi(__t2, __a1, 0));
+        emit(__sw(__ra, __sp, -4));
</file context>

[cubic-dev-ai]

P2: Dynamic runs can use the developer’s home directory as qemu’s sysroot when the selected cross compiler has no configured sysroot. Treat an empty --print-sysroot result like / so the existing target-prefix fallback locates the loader.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At mk/common.mk, line 46:

<comment>Dynamic runs can use the developer’s home directory as qemu’s sysroot when the selected cross compiler has no configured sysroot. Treat an empty `--print-sysroot` result like `/` so the existing target-prefix fallback locates the loader.</comment>

<file context>
@@ -22,6 +22,47 @@ NO_COLOR = \e[0m
+
+        ARCH_CC = $(CROSS_COMPILE)gcc
+
+        LD_LINUX_PATH := $(shell cd $(shell $(ARCH_CC) --print-sysroot) 2>/dev/null && pwd)
+        ifeq ("$(LD_LINUX_PATH)","/")
+            LD_LINUX_PATH := $(shell dirname "$(shell which $(ARCH_CC))")/..
</file context>

Suggested change

	LD_LINUX_PATH := $(shell cd $(shell $(ARCH_CC) --print-sysroot) 2>/dev/null && pwd)
	LD_LINUX_PATH := $(shell sysroot="$$($(ARCH_CC) --print-sysroot)"; if [ -n "$$sysroot" ]; then cd "$$sysroot" 2>/dev/null && pwd || printf /; else printf /; fi)

[cubic-dev-ai]

P3: The formula N * 4 for the N-th function's GOT offset is inconsistent with the GOT[2] → offset 0 entry. If 1st function is offset 0, then N-th function offset should be (N-1)*4. Or if GOT[2] is at offset 8, then N-th function offset is (N+1)*4. Either way the table and formula contradict each other.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/dynamic-linking.md, line 281:

<comment>The formula `N * 4` for the N-th function's GOT offset is inconsistent with the GOT[2] → offset 0 entry. If 1st function is offset 0, then N-th function offset should be (N-1)*4. Or if GOT[2] is at offset 8, then N-th function offset is (N+1)*4. Either way the table and formula contradict each other.</comment>

<file context>
@@ -198,6 +254,49 @@ ldr  pc, [ip]
+  | 1st function      | `GOT[2]`                  | `0`           |
+  | 2nd function      | `GOT[3]`                  | `4`           |
+  | ...               | ...                       | ...           |
+  | N-th function     | `GOT[N + 1]`              | `N * 4`       |
+
+- `t2` is `%hi(%pcrel(.got))`, but it is not used by `__dl_runtime_resolve()`.
</file context>

Suggested change

	| N-th function | `GOT[N + 1]` | `N * 4` |
	| N-th function | `GOT[N + 1]` | `(N - 1) * 4` |

[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.