feat(runtime): add intrinsic resolution for TLS native calls

Wire vmpilot_tls_read64/write64/read32/write32 into the NATIVE_CALL
dispatch pipeline via a sentinel-based intrinsic resolution mechanism.

The blob stores a reserved target_offset (INTRINSIC_BASE + id) for
runtime-provided functions.  VmEngine::create() resolves these to
actual function pointers before any instruction executes, so the
NATIVE_CALL handler works unchanged.

Backend contract documented in vm_intrinsics.hpp: the backend must
emit NATIVE_CALL + TransitionEntry with the sentinel target_offset
when it encounters segment-prefixed memory accesses (fs:/gs:/TPIDR_EL0).

Author: scc-tw

runtime/CMakeLists.txt

@@ -55,6 +55,7 @@ add_library(VMPilot_Runtime STATIC
     src/oram_strategies.cpp
     src/classify_args.cpp
     src/tls_helpers.cpp
+    src/vm_intrinsics.cpp
     src/blob_builder.cpp
     src/program_builder.cpp
     src/handler_detail.cpp
@@ -138,6 +139,7 @@ if(ENABLE_TESTS)
         test_cfg_patterns
         test_native_call
         test_policy_matrix
+        test_tls_intrinsic
     )
         vmpilot_add_runtime_test(${_t} SOURCES test/integration/${_t}.cpp)
     endforeach()

runtime/include/vm_intrinsics.hpp

@@ -0,0 +1,81 @@
+#pragma once
+#ifndef __RUNTIME_VM_INTRINSICS_HPP__
+#define __RUNTIME_VM_INTRINSICS_HPP__
+
+/// @file vm_intrinsics.hpp
+/// @brief Intrinsic native call resolution for runtime-provided functions.
+///
+/// The NATIVE_CALL handler resolves targets via
+///   target_offset + load_base_delta
+/// which works for functions in the protected binary.  Runtime-internal
+/// functions (e.g. TLS helpers) live in the runtime library and their
+/// addresses are unknown at blob-build time.
+///
+/// Convention: the blob stores a sentinel value in target_offset to
+/// indicate an intrinsic.  The runtime resolves it to the actual
+/// function pointer at engine creation (VmEngine::create), before any
+/// instruction executes.
+///
+/// ─── Backend Contract ────────────────────────────────────────────────
+///
+/// When the backend (SimpleBackend / LLVM backend) encounters a
+/// segment-prefixed memory access in the protected region:
+///
+///   x86-64:  fs:[offset]              → TLS_READ64 / TLS_WRITE64
+///   x86-32:  gs:[offset]              → TLS_READ32 / TLS_WRITE32
+///   ARM64:   mrs TPIDR_EL0 + ldr/str  → TLS_READ64 / TLS_WRITE64
+///
+/// It must emit:
+///
+///   1. Load the TLS offset into r0.
+///      For writes: offset in r0, value in r1.
+///
+///   2. A NATIVE_CALL instruction with insn.aux = transition entry index.
+///
+///   3. A TransitionEntry in the blob with:
+///        target_offset = intrinsic_target(IntrinsicId::TLS_READ64)
+///                      = INTRINSIC_BASE + id
+///        arg_count     = te_pack_arg_count(1, 0, false, false, false)
+///                        (2 for write variants)
+///        call_site_ip  = instruction index of the NATIVE_CALL
+///
+/// The runtime resolves the sentinel to the actual function pointer at
+/// engine creation time.  The result (for reads) is returned in r0.
+/// ─────────────────────────────────────────────────────────────────────
+
+#include <cstdint>
+
+namespace VMPilot::Runtime {
+
+/// Sentinel base for intrinsic target_offset values.
+/// Top of the 64-bit address space — never a real function pointer.
+inline constexpr uint64_t INTRINSIC_BASE = 0xFFFF'FFFF'FFFF'FF00ULL;
+
+/// Well-known intrinsic IDs.
+enum class IntrinsicId : uint8_t {
+    TLS_READ64  = 0,   ///< vmpilot_tls_read64(offset) -> uint64_t
+    TLS_WRITE64 = 1,   ///< vmpilot_tls_write64(offset, value) -> void
+    TLS_READ32  = 2,   ///< vmpilot_tls_read32(offset) -> uint64_t
+    TLS_WRITE32 = 3,   ///< vmpilot_tls_write32(offset, value) -> void
+
+    COUNT               ///< must be last
+};
+
+/// Produce the sentinel target_offset for blob builders.
+constexpr uint64_t intrinsic_target(IntrinsicId id) noexcept {
+    return INTRINSIC_BASE + static_cast<uint8_t>(id);
+}
+
+/// Check whether a target_offset is an intrinsic sentinel.
+constexpr bool is_intrinsic_target(uint64_t target_offset) noexcept {
+    return target_offset >= INTRINSIC_BASE
+        && target_offset < INTRINSIC_BASE + static_cast<uint8_t>(IntrinsicId::COUNT);
+}
+
+/// Resolve an intrinsic ID to the actual function pointer.
+/// Returns nullptr for unknown IDs.
+void* resolve_intrinsic(IntrinsicId id) noexcept;
+
+}  // namespace VMPilot::Runtime
+
+#endif  // __RUNTIME_VM_INTRINSICS_HPP__

runtime/src/vm_engine.cpp

@@ -7,6 +7,7 @@
 /// ensure link-time availability without exposing implementation in the header.
 
 #include "vm_engine.hpp"
+#include "vm_intrinsics.hpp"
 
 #include <vm/vm_encoding.hpp>
 #include <vm/hardware_rng.hpp>
@@ -122,6 +123,24 @@ VmEngine<Policy, Oram>::create(
     auto raw_trans = m->blob.native_calls();
     m->native_calls.assign(raw_trans.begin(), raw_trans.end());
 
+    // 5b. Resolve intrinsic native calls (runtime-provided functions).
+    //
+    // The blob stores a sentinel target_offset (INTRINSIC_BASE + id) for
+    // built-in intrinsics whose addresses are unknown at blob-build time.
+    // Patch them here so the handler's (target_offset + load_base_delta)
+    // yields the correct function pointer.
+    for (auto& te : m->native_calls) {
+        if (is_intrinsic_target(te.target_offset)) {
+            auto id = static_cast<IntrinsicId>(
+                te.target_offset - INTRINSIC_BASE);
+            auto* fn = resolve_intrinsic(id);
+            if (!fn)
+                return tl::make_unexpected(DiagnosticCode::NativeCallBridgeFailed);
+            te.target_offset = reinterpret_cast<uint64_t>(fn)
+                             - static_cast<uint64_t>(load_base_delta);
+        }
+    }
+
     // 6. Derive global memory encoding (LUT-based, unchanged from doc 15)
     derive_memory_tables(stored_seed, m->mem.encode, m->mem.decode);
 

runtime/src/vm_intrinsics.cpp

@@ -0,0 +1,24 @@
+/// @file vm_intrinsics.cpp
+/// @brief Intrinsic ID to function pointer resolution.
+
+#include "vm_intrinsics.hpp"
+#include <tls_helpers.hpp>
+
+namespace VMPilot::Runtime {
+
+void* resolve_intrinsic(IntrinsicId id) noexcept {
+    switch (id) {
+    case IntrinsicId::TLS_READ64:
+        return reinterpret_cast<void*>(&vmpilot_tls_read64);
+    case IntrinsicId::TLS_WRITE64:
+        return reinterpret_cast<void*>(&vmpilot_tls_write64);
+    case IntrinsicId::TLS_READ32:
+        return reinterpret_cast<void*>(&vmpilot_tls_read32);
+    case IntrinsicId::TLS_WRITE32:
+        return reinterpret_cast<void*>(&vmpilot_tls_write32);
+    default:
+        return nullptr;
+    }
+}
+
+}  // namespace VMPilot::Runtime

runtime/test/integration/test_tls_intrinsic.cpp

@@ -0,0 +1,200 @@
+/// @file test_tls_intrinsic.cpp
+/// @brief Integration test: TLS intrinsic resolution via NATIVE_CALL.
+///
+/// Verifies that a blob containing an intrinsic sentinel target_offset
+/// (e.g. TLS_READ64) is correctly resolved at engine creation, and the
+/// NATIVE_CALL handler dispatches to vmpilot_tls_read64.
+
+#include "test_blob_builder.hpp"
+
+#include "vm_engine.hpp"
+#include "vm_intrinsics.hpp"
+
+#include <tls_helpers.hpp>
+#include <vm/vm_opcode.hpp>
+#include <vm/vm_blob.hpp>
+
+#include <gtest/gtest.h>
+
+#include <cstdint>
+
+using namespace VMPilot::Runtime;
+using namespace VMPilot::Common::VM;
+using namespace VMPilot::Test;
+
+static uint8_t flags_none() { return 0; }
+
+// ============================================================================
+// Test: TLS_READ64 intrinsic through NATIVE_CALL
+// ============================================================================
+
+TEST(TlsIntrinsic, Read64ViaIntrinsic) {
+    uint8_t seed[32];
+    fill_seed(seed);
+
+    // Build a single-BB program: NATIVE_CALL(aux=0) → HALT
+    TestBB bb{};
+    bb.bb_id = 1;
+    bb.epoch = 0;
+    bb.live_regs_bitmap = 0xFFFF;
+    bb.flags = 0;
+    fill_epoch(bb.epoch_seed, 0xA0);
+
+    bb.instructions = {
+        {VmOpcode::NATIVE_CALL, flags_none(), 0, 0, 0},  // aux=0 → first transition entry
+        {VmOpcode::HALT, flags_none(), 0, 0, 0},
+    };
+
+    // Transition entry: intrinsic sentinel for TLS_READ64, 1 arg
+    TestNativeCall tc{};
+    tc.call_site_ip = 0;
+    tc.arg_count    = te_pack_arg_count(1, 0, false, false, false);
+    tc.target_addr  = intrinsic_target(IntrinsicId::TLS_READ64);
+
+    auto blob = build_test_blob(seed, {bb}, {}, false, {tc});
+
+    // r0 = TLS offset.  On most platforms, offset 0 of the thread pointer
+    // contains a self-pointer or well-known value.  We read it directly
+    // for the expected result.
+    uint64_t tls_offset = 0;
+    uint64_t expected = vmpilot_tls_read64(tls_offset);
+
+    uint64_t initial_regs[16] = {};
+    initial_regs[0] = tls_offset;
+
+    auto engine = VmEngine<DebugPolicy, DirectOram>::create(
+        blob.data(), blob.size(), seed, 0, initial_regs, 1);
+    ASSERT_TRUE(engine.has_value()) << "Engine creation should succeed";
+
+    auto r = engine->execute();
+    ASSERT_TRUE(r.has_value()) << "Execution should succeed";
+    EXPECT_EQ(r->return_value, expected)
+        << "TLS_READ64 intrinsic should return the same value as vmpilot_tls_read64(0)";
+}
+
+// ============================================================================
+// Test: TLS_READ32 intrinsic through NATIVE_CALL
+// ============================================================================
+
+TEST(TlsIntrinsic, Read32ViaIntrinsic) {
+    uint8_t seed[32];
+    fill_seed(seed);
+
+    TestBB bb{};
+    bb.bb_id = 1;
+    bb.epoch = 0;
+    bb.live_regs_bitmap = 0xFFFF;
+    bb.flags = 0;
+    fill_epoch(bb.epoch_seed, 0xA1);
+
+    bb.instructions = {
+        {VmOpcode::NATIVE_CALL, flags_none(), 0, 0, 0},
+        {VmOpcode::HALT, flags_none(), 0, 0, 0},
+    };
+
+    TestNativeCall tc{};
+    tc.call_site_ip = 0;
+    tc.arg_count    = te_pack_arg_count(1, 0, false, false, false);
+    tc.target_addr  = intrinsic_target(IntrinsicId::TLS_READ32);
+
+    auto blob = build_test_blob(seed, {bb}, {}, false, {tc});
+
+    uint64_t tls_offset = 0;
+    uint64_t expected = vmpilot_tls_read32(tls_offset);
+
+    uint64_t initial_regs[16] = {};
+    initial_regs[0] = tls_offset;
+
+    auto engine = VmEngine<DebugPolicy, DirectOram>::create(
+        blob.data(), blob.size(), seed, 0, initial_regs, 1);
+    ASSERT_TRUE(engine.has_value());
+
+    auto r = engine->execute();
+    ASSERT_TRUE(r.has_value());
+    EXPECT_EQ(r->return_value, expected)
+        << "TLS_READ32 intrinsic should return the same value as vmpilot_tls_read32(0)";
+}
+
+// ============================================================================
+// Test: intrinsic resolution with non-zero load_base_delta
+// ============================================================================
+
+TEST(TlsIntrinsic, ResolutionWithNonZeroDelta) {
+    uint8_t seed[32];
+    fill_seed(seed);
+
+    TestBB bb{};
+    bb.bb_id = 1;
+    bb.epoch = 0;
+    bb.live_regs_bitmap = 0xFFFF;
+    bb.flags = 0;
+    fill_epoch(bb.epoch_seed, 0xA2);
+
+    bb.instructions = {
+        {VmOpcode::NATIVE_CALL, flags_none(), 0, 0, 0},
+        {VmOpcode::HALT, flags_none(), 0, 0, 0},
+    };
+
+    TestNativeCall tc{};
+    tc.call_site_ip = 0;
+    tc.arg_count    = te_pack_arg_count(1, 0, false, false, false);
+    tc.target_addr  = intrinsic_target(IntrinsicId::TLS_READ64);
+
+    auto blob = build_test_blob(seed, {bb}, {}, false, {tc});
+
+    uint64_t tls_offset = 0;
+    uint64_t expected = vmpilot_tls_read64(tls_offset);
+
+    uint64_t initial_regs[16] = {};
+    initial_regs[0] = tls_offset;
+
+    // Non-zero delta: intrinsic resolution must compensate correctly
+    int64_t delta = 0x1000;
+    auto engine = VmEngine<DebugPolicy, DirectOram>::create(
+        blob.data(), blob.size(), seed, delta, initial_regs, 1);
+    ASSERT_TRUE(engine.has_value())
+        << "Engine creation should succeed with non-zero load_base_delta";
+
+    auto r = engine->execute();
+    ASSERT_TRUE(r.has_value());
+    EXPECT_EQ(r->return_value, expected)
+        << "Intrinsic should produce correct result regardless of load_base_delta";
+}
+
+// ============================================================================
+// Test: sentinel outside intrinsic range is NOT resolved as intrinsic
+// ============================================================================
+
+TEST(TlsIntrinsic, OutOfRangeSentinelNotResolvedAsIntrinsic) {
+    // INTRINSIC_BASE + COUNT falls outside is_intrinsic_target() range,
+    // so it's treated as a regular (non-intrinsic) native call target.
+    // Creation succeeds, but execution fails because the address is garbage.
+    uint8_t seed[32];
+    fill_seed(seed);
+
+    TestBB bb{};
+    bb.bb_id = 1;
+    bb.epoch = 0;
+    bb.live_regs_bitmap = 0xFFFF;
+    bb.flags = 0;
+    fill_epoch(bb.epoch_seed, 0xA3);
+
+    bb.instructions = {
+        {VmOpcode::NATIVE_CALL, flags_none(), 0, 0, 0},
+        {VmOpcode::HALT, flags_none(), 0, 0, 0},
+    };
+
+    TestNativeCall tc{};
+    tc.call_site_ip = 0;
+    tc.arg_count    = te_pack_arg_count(1, 0, false, false, false);
+    tc.target_addr  = INTRINSIC_BASE + static_cast<uint8_t>(IntrinsicId::COUNT);
+
+    auto blob = build_test_blob(seed, {bb}, {}, false, {tc});
+
+    // Creation succeeds — the out-of-range sentinel is not recognized
+    auto engine = VmEngine<DebugPolicy, DirectOram>::create(
+        blob.data(), blob.size(), seed);
+    EXPECT_TRUE(engine.has_value())
+        << "Out-of-range sentinel should not be treated as intrinsic; "
+           "creation succeeds (it looks like a regular native call target)";
+}