MIPS64 real-ELF (glibc) support depends on upstream unicorn vtlb fixes (unicorn #2272/#2347, #2345/#2346)

[retrocpugeek]

Summary

Real-world (glibc / PIE) MIPS64 ELF support in Qiling depends on two upstream unicorn fixes that are not yet in a released unicorn. This issue tracks that cross-repo dependency so the MIPS64 work can rely on it once unicorn ships the fixes.

The MIPS64 shellcode and freestanding (syscall-only) static ELF paths already work on stock pip unicorn. The glibc-ELF paths (dynamic + PIE binaries, TLS setup, pthreads) do not — they trip two bugs in unicorn's virtual-TLB (UC_TLB_VIRTUAL) code path.

Background: why Qiling needs UC_TLB_VIRTUAL for MIPS64

unicorn's MIPS64 CPU-MMU only executes in the low ~2 GB (useg); at/above 0x80000000 it raises an address exception. But real n64 ELFs link at 0x120000000 (~4.8 GB) and PIE binaries load at 0x555555…, and Qiling's 64-bit profile places stack/mmap above 4 GB. The fix (in qiling/arch/mips64.py) is to switch the MIPS64 engine into UC_TLB_VIRTUAL mode with an identity-mapping UC_HOOK_TLB_FILL callback, which bypasses the CPU-MMU segment checks while keeping virtual == physical, so Qiling's flat memory model works unchanged.

Enabling that soft-TLB path is what exposed the two unicorn bugs below.

Blocking unicorn bugs

1. Spurious EXCP_RI after a delay-slot TLB fill — unicorn issue #2272, fix PR #2347.

glibc's __libc_setup_tls scans the program headers for PT_TLS using a b→bne "branch-onto-branch" (back-to-back delay slots). Under UC_TLB_VIRTUAL, unicorn_fill_tlb() unconditionally called cpu_restore_state(); on a successful fill this re-injected the branch-delay hflags (MIPS_HFLAG_B|BDS32) into the live env, so the next translation block (the branch target) was generated with BMASK set → spurious Reserved-Instruction exception (intno 20). The RI vectors PC→0 and Qiling dies with UC_ERR_FETCH_UNMAPPED. The fix removes the unconditional restore (the exception path still restores via cpu_loop_exit_restore). (unicorn's own PR #2273 attempted #2272 but only covered the no-hook fallback path; #2347 fixes both the hooked and unhooked cases.)

2. Spurious AdEL on ll/lld from high addresses — unicorn issue #2345, fix PR #2346.

Right after TLS setup, glibc takes an ll/sc spinlock. ll/lld are emitted as helpers that perform the load through the soft-TLB (works), but also call do_translate_address purely to set CP0_LLAddr — and that walks the MIPS segments (xuseg, UX unset for a >2 GB address) → TLBRET_BADADDR → spurious address error (intno 12). The fix skips the segment-walking translate in vtlb mode and records the hook-mapped physical address into CP0_LLAddr instead (alignment check preserved, so a genuinely misaligned ll still faults correctly).

Both are contained to the UC_TLB_VIRTUAL path (not present in upstream QEMU, which has no such mode) and are in the same family.

Impact / CI gating

• ✅ MIPS64 shellcode and freestanding static ELF tests pass on stock pip unicorn 2.1.3 and are safe for CI today.
• ⛔ MIPS64 glibc-ELF tests (dynamic + PIE binaries, statx/stat64 end-to-end, multithreading) require the two unicorn fixes above and will fail on stock unicorn / CI until unicorn ships them in a release.

The eventual (reopened) MIPS64 arch PR should keep the glibc-ELF tests gated/held until a unicorn release includes both fixes, then flip them on and reference this issue.

Related Qiling fixes (independent — run on stock unicorn)

These were found while bringing MIPS64 up but are standalone and do not depend on the unicorn fixes: #1633 (statx big-endian), #1635 (getdents alignment), #1638 (clone3), #1640 (MIPS socket options).

[wtdcode]

unicorn's MIPS64 CPU-MMU only executes in the low ~2 GB (useg); at/above 0x80000000 it raises an address exception. But real n64 ELFs link at 0x120000000 (~4.8 GB)

This sounds slightly strange to me. What is n64 ELFs, or could you illustrate what you are emulating?

[retrocpugeek]

"n64" is the MIPS N64 ABI — the 64-bit MIPS ABI (o32 / n32 / n64), i.e. the *-linux-gnuabi64 triplet. So this is just an ordinary 64-bit MIPS Linux glibc userspace program.

o32 = "old" 32-bit ABI (the original/legacy ABI)
n32 = "new" 32-bit ABI (introduced for 64-bit MIPS systems) 64-bit hardware, 32-bit pointers
n64 = "new" 64-bit ABI (introduced for 64-bit MIPS systems) full 64-bit everything

The part that sounds strange — unicorn only executing the low ~2 GB while the ELF lives much higher — is a property of the ABI. A plain non-PIE n64 executable links at a default base of 0x120000000 (~4.8 GB), above unicorn's MIPS64 useg, which is what forces the UC_TLB_VIRTUAL identity-map and in turn trips the two vtlb bugs.

Concretely, examples/rootfs/mips64_linux/bin/mips64_hello (Ubuntu gcc-12-mips64-linux-gnuabi64):

$ readelf -h mips64_hello | grep -E 'Class|Type|Entry'
  Class:               ELF64
  Type:                EXEC (Executable file)
  Entry point address: 0x120000920
$ readelf -l mips64_hello | grep LOAD
  LOAD  0x0000000000000000  0x0000000120000000  R E
  LOAD  0x000000000000fff0  0x000000012001fff0  RW
$ readelf -A mips64_hello | grep -E 'ISA:|GPR'
  ISA: MIPS64r2
  GPR size: 64

To show the 0x120000000 base isn't a quirk of one toolchain, here's the same thing built with Buildroot's mips64-buildroot-linux-gnu-gcc 14.3.0, -no-pie:

$ readelf -h mips64_hello_buildroot | grep -E 'Type|Entry'
  Type:                EXEC (Executable file)
  Entry point address: 0x120000880
$ readelf -l mips64_hello_buildroot | grep LOAD
  LOAD  0x0000000000000000  0x0000000120000000  R E
  LOAD  0x000000000000fff0  0x000000012001fff0  RW
$ readelf -p .comment mips64_hello_buildroot
  GCC: (Buildroot 2026.02.3) 14.3.0

Both chains land n64 non-PIE executables at 0x120000000. (Buildroot defaults to PIE — e.g. its stock busybox — which instead loads high at runtime; under Qiling's 64-bit profile a PIE maps around 0x5555_5555_0000, so it hits the same vtlb path from the other direction.)

The exact binaries are on my fork if you want to run/inspect them:

• mips64_hello (dynamic, Ubuntu chain): https://github.com/retrocpugeek/rootfs/blob/add-mips64/mips64_linux/bin/mips64_hello
• mips64_hello_buildroot (non-PIE, Buildroot chain): https://github.com/retrocpugeek/rootfs/blob/add-mips64/mips64_linux/bin/mips64_hello_buildroot

Build recipe for either, for reference:

# Ubuntu:
apt install gcc-12-mips64-linux-gnuabi64        # -mips64el- for LE
mips64-linux-gnuabi64-gcc -no-pie -o mips64_hello hello.c
# Buildroot: mips64[el] + BR2_MIPS_NABI64=y + BR2_TOOLCHAIN_BUILDROOT_GLIBC=y