[GR-67607] Backport to 25.0: Refactor UnregisteredForeignStubException into a missing registration error

sdk/src/org.graalvm.nativeimage/snapshot.sigtest

@@ -232,6 +232,10 @@ meth public abstract void fatalError()
 meth public abstract void flush()
 meth public abstract void log(org.graalvm.nativeimage.c.type.CCharPointer,org.graalvm.word.UnsignedWord)
 
+CLSS public final org.graalvm.nativeimage.MissingForeignRegistrationError
+cons public init(java.lang.String)
+supr java.lang.LinkageError
+
 CLSS public final org.graalvm.nativeimage.MissingJNIRegistrationError
 cons public init(java.lang.String,java.lang.Class<?>,java.lang.Class<?>,java.lang.String,java.lang.String)
 meth public java.lang.Class<?> getDeclaringClass()

sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/MissingForeignRegistrationError.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * The Universal Permissive License (UPL), Version 1.0
+ *
+ * Subject to the condition set forth below, permission is hereby granted to any
+ * person obtaining a copy of this software, associated documentation and/or
+ * data (collectively the "Software"), free of charge and under any and all
+ * copyright rights in the Software, and any and all patent rights owned or
+ * freely licensable by each licensor hereunder covering either (i) the
+ * unmodified Software as contributed to or provided by such licensor, or (ii)
+ * the Larger Works (as defined below), to deal in both
+ *
+ * (a) the Software, and
+ *
+ * (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+ * one is included with the Software each a "Larger Work" to which the Software
+ * is contributed by such licensors),
+ *
+ * without restriction, including without limitation the rights to copy, create
+ * derivative works of, display, perform, and distribute the Software and make,
+ * use, sell, offer for sale, import, export, have made, and have sold the
+ * Software and the Larger Work(s), and to sublicense the foregoing rights on
+ * either these or other terms.
+ *
+ * This license is subject to the following condition:
+ *
+ * The above copyright notice and either this complete permission notice or at a
+ * minimum a reference to the UPL must be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package org.graalvm.nativeimage;
+
+/**
+ * This error is thrown when a query through the Foreign Function and Memory (FFM) API did not get
+ * appropriately registered at build-time.
+ *
+ * @since 25.0
+ */
+@SuppressWarnings("serial")
+public final class MissingForeignRegistrationError extends LinkageError {
+    public MissingForeignRegistrationError(String message) {
+        super(message);
+    }
+}

substratevm/src/com.oracle.svm.core.foreign/src/com/oracle/svm/core/foreign/ForeignFunctionsRuntime.java

@@ -31,14 +31,17 @@
 import java.lang.foreign.MemorySegment;
 import java.lang.foreign.MemorySegment.Scope;
 import java.lang.invoke.MethodHandle;
+import java.lang.invoke.MethodType;
 import java.util.HashMap;
 import java.util.Locale;
 import java.util.Map;
+import java.util.Set;
 import java.util.function.BiConsumer;
 
 import org.graalvm.collections.EconomicMap;
 import org.graalvm.collections.Pair;
 import org.graalvm.nativeimage.ImageSingletons;
+import org.graalvm.nativeimage.MissingForeignRegistrationError;
 import org.graalvm.nativeimage.Platform;
 import org.graalvm.nativeimage.Platforms;
 import org.graalvm.nativeimage.c.function.CFunctionPointer;
@@ -48,6 +51,7 @@
 
 import com.oracle.svm.core.ForeignSupport;
 import com.oracle.svm.core.FunctionPointerHolder;
+import com.oracle.svm.core.MissingRegistrationUtils;
 import com.oracle.svm.core.OS;
 import com.oracle.svm.core.SubstrateOptions;
 import com.oracle.svm.core.SubstrateUtil;
@@ -131,15 +135,15 @@ public void addDirectUpcallStubPointer(DirectMethodHandleDesc desc, JavaEntryPoi
     CFunctionPointer getDowncallStubPointer(NativeEntryPointInfo nep) {
         FunctionPointerHolder holder = downcallStubs.get(nep);
         if (holder == null) {
-            throw new UnregisteredForeignStubException(nep);
+            throw MissingForeignRegistrationUtils.reportDowncall(nep);
         }
         return holder.functionPointer;
     }
 
     CFunctionPointer getUpcallStubPointer(JavaEntryPointInfo jep) {
         FunctionPointerHolder holder = upcallStubs.get(jep);
         if (holder == null) {
-            throw new UnregisteredForeignStubException(jep);
+            throw MissingForeignRegistrationUtils.reportUpcall(jep);
         }
         return holder.functionPointer;
     }
@@ -214,24 +218,32 @@ void freeTrampoline(long addr) {
         }
     }
 
-    @SuppressWarnings("serial")
-    public static class UnregisteredForeignStubException extends RuntimeException {
-
-        UnregisteredForeignStubException(NativeEntryPointInfo nep) {
-            super(generateMessage(nep));
+    public static class MissingForeignRegistrationUtils extends MissingRegistrationUtils {
+        public static MissingForeignRegistrationError reportDowncall(NativeEntryPointInfo nep) {
+            MissingForeignRegistrationError mfre = new MissingForeignRegistrationError(foreignRegistrationMessage("downcall", nep.methodType()));
+            report(mfre);
+            return mfre;
         }
 
-        UnregisteredForeignStubException(JavaEntryPointInfo jep) {
-            super(generateMessage(jep));
+        public static MissingForeignRegistrationError reportUpcall(JavaEntryPointInfo jep) {
+            MissingForeignRegistrationError mfre = new MissingForeignRegistrationError(foreignRegistrationMessage("upcall", jep.cMethodType()));
+            report(mfre);
+            return mfre;
         }
 
-        private static String generateMessage(NativeEntryPointInfo nep) {
-            return "Cannot perform downcall with leaf type " + nep.methodType() + " as it was not registered at compilation time.";
+        private static String foreignRegistrationMessage(String failedAction, MethodType methodType) {
+            return registrationMessage("perform " + failedAction + " with leaf type", methodType.toString(), "", "", "foreign", "foreign");
         }
 
-        private static String generateMessage(JavaEntryPointInfo jep) {
-            return "Cannot perform upcall with leaf type " + jep.cMethodType() + " as it was not registered at compilation time.";
+        private static void report(MissingForeignRegistrationError exception) {
+            StackTraceElement responsibleClass = getResponsibleClass(exception, foreignEntryPoints);
+            MissingRegistrationUtils.report(exception, responsibleClass);
         }
+
+        private static final Map<String, Set<String>> foreignEntryPoints = Map.of(
+                        "jdk.internal.foreign.abi.AbstractLinker", Set.of(
+                                        "downcallHandle",
+                                        "upcallStub"));
     }
 
     /**

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/MissingRegistrationUtils.java

@@ -33,6 +33,7 @@
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
+import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.atomic.AtomicReference;
@@ -219,6 +220,24 @@ protected static String interfacesString(Class<?>[] classes) {
                         .collect(Collectors.joining(",", "[", "]"));
     }
 
+    protected static StackTraceElement getResponsibleClass(Throwable t, Map<String, Set<String>> entryPoints) {
+        StackTraceElement[] stackTrace = t.getStackTrace();
+        boolean returnNext = false;
+        for (StackTraceElement stackTraceElement : stackTrace) {
+            if (entryPoints.getOrDefault(stackTraceElement.getClassName(), Set.of()).contains(stackTraceElement.getMethodName())) {
+                /*
+                 * Multiple functions with the same name can be called in succession, like the
+                 * Class.forName caller-sensitive adapters. We skip those until we find a method
+                 * that is not a monitored reflection entry point.
+                 */
+                returnNext = true;
+            } else if (returnNext) {
+                return stackTraceElement;
+            }
+        }
+        return null;
+    }
+
     public static final class ExitException extends Error {
         @Serial//
         private static final long serialVersionUID = -3638940737396726143L;

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/reflect/MissingReflectionRegistrationUtils.java

@@ -157,7 +157,7 @@ private static String reflectionError(String failedAction, String elementDescrip
     }
 
     private static void report(MissingReflectionRegistrationError exception) {
-        StackTraceElement responsibleClass = getResponsibleClass(exception);
+        StackTraceElement responsibleClass = getResponsibleClass(exception, reflectionEntryPoints);
         MissingRegistrationUtils.report(exception, responsibleClass);
     }
 
@@ -197,22 +197,4 @@ private static void report(MissingReflectionRegistrationError exception) {
                     "sun.misc.Unsafe", Set.of("allocateInstance"),
                     /* For jdk.internal.misc.Unsafe.allocateInstance(), which is intrinsified */
                     SubstrateAllocationSnippets.class.getName(), Set.of("slowPathHubOrUnsafeInstantiationError"));
-
-    private static StackTraceElement getResponsibleClass(Throwable t) {
-        StackTraceElement[] stackTrace = t.getStackTrace();
-        boolean returnNext = false;
-        for (StackTraceElement stackTraceElement : stackTrace) {
-            if (reflectionEntryPoints.getOrDefault(stackTraceElement.getClassName(), Set.of()).contains(stackTraceElement.getMethodName())) {
-                /*
-                 * Multiple functions with the same name can be called in succession, like the
-                 * Class.forName caller-sensitive adapters. We skip those until we find a method
-                 * that is not a monitored reflection entry point.
-                 */
-                returnNext = true;
-            } else if (returnNext) {
-                return stackTraceElement;
-            }
-        }
-        return null;
-    }
 }