[GR-51436] Add @BasedOnJDKFile annotation

PullRequest: graal/16861

compiler/src/jdk.graal.compiler.processor/src/jdk/graal/compiler/processor/AbstractProcessor.java

@@ -342,7 +342,7 @@ public void createProviderFile(String providerClassName, String serviceClassName
      * Determines if a given exception is (most likely) caused by
      * <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=367599">Bug 367599</a>.
      */
-    private static boolean isBug367599(Throwable t) {
+    protected static boolean isBug367599(Throwable t) {
         if (t instanceof FilerException) {
             for (StackTraceElement ste : t.getStackTrace()) {
                 if (ste.toString().contains("org.eclipse.jdt.internal.apt.pluggable.core.filer.IdeFilerImpl.create")) {

substratevm/mx.substratevm/suite.py

@@ -251,7 +251,8 @@
                 "compiler:GRAAL_PROCESSOR"
             ],
             "requires" : [
-                "java.compiler" # javax.annotation.processing.*
+                "java.compiler", # javax.annotation.processing.*
+                "jdk.compiler", # com.sun.source.util.*
             ],
             "javaCompliance" : "21+",
             "checkstyle" : "com.oracle.svm.core",

substratevm/src/com.oracle.svm.core.windows/src/com/oracle/svm/core/windows/WindowsUtils.java

@@ -29,6 +29,7 @@
 import java.io.FileDescriptor;
 import java.io.IOException;
 
+import com.oracle.svm.core.util.BasedOnJDKFile;
 import org.graalvm.nativeimage.StackValue;
 import org.graalvm.nativeimage.c.function.CFunctionPointer;
 import org.graalvm.nativeimage.c.struct.CPointerTo;
@@ -170,6 +171,8 @@ static void writeBytes(FileDescriptor descriptor, byte[] bytes, int off, int len
 
     /** Retrieve a nanosecond counter for elapsed time measurement. */
     @Uninterruptible(reason = "Called from uninterruptible code.", mayBeInlined = true)
+    @BasedOnJDKFile("src/hotspot/os/windows/os_windows.cpp#L970-L977")
+    @BasedOnJDKFile("src/hotspot/os/windows/os_windows.cpp#L1075-L1081")
     public static long getNanoCounter() {
         if (performanceFrequency == 0L) {
             CLongPointer count = StackValue.get(CLongPointer.class);

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/amd64/AMD64LibCHelper.java

@@ -36,17 +36,14 @@
 import org.graalvm.nativeimage.c.type.CCharPointer;
 import org.graalvm.word.PointerBase;
 
-import jdk.graal.compiler.lir.SyncPort;
+import com.oracle.svm.core.util.BasedOnJDKFile;
 
-// @formatter:off
-@SyncPort(from = "https://github.com/openjdk/jdk/blob/34f85ee94e8b45bcebbf8ba52a38c92a7185b54a/src/hotspot/cpu/x86/vm_version_x86.hpp#L40-L304",
-          sha1 = "5cc04c08555379223cc02a15774159076d3cdf1d")
 /*
  * To be kept in sync with:
  *  - substratevm/src/com.oracle.svm.native.libchelper/include/amd64hotspotcpuinfo.h
  *  - substratevm/src/com.oracle.svm.native.libchelper/src/cpuid.c
  */
-// @formatter:on
+@BasedOnJDKFile("src/hotspot/cpu/x86/vm_version_x86.hpp#L40-L304")
 @CLibrary(value = "libchelper", requireStatic = true)
 public class AMD64LibCHelper {
     @Platforms(Platform.AMD64.class)

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/jni/headers/JNIVersionJDKLatest.java

@@ -24,6 +24,7 @@
  */
 package com.oracle.svm.core.jni.headers;
 
+import com.oracle.svm.core.util.BasedOnJDKFile;
 import org.graalvm.nativeimage.c.CContext;
 import org.graalvm.nativeimage.c.constant.CConstant;
 
@@ -46,6 +47,7 @@ public final class JNIVersionJDKLatest {
      * gets available, the "value" property of the CConstant annotation below must be removed.
      */
     @CConstant(value = "JNI_VERSION_21")
+    @BasedOnJDKFile("src/java.base/share/native/include/jni.h#L1985-L1996")
     public static native int JNI_VERSION_LATEST();
 
     // Checkstyle: resume

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/util/BasedOnJDKFile.java

@@ -0,0 +1,80 @@
+/*
+ * Copyright (c) 2024, 2024, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package com.oracle.svm.core.util;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.graalvm.nativeimage.Platform;
+import org.graalvm.nativeimage.Platforms;
+
+/**
+ * Documents that the element is based on a JDK source file. This is mainly useful for non-Java
+ * sources like C++ files. For Java classes, {@link BasedOnJDKClass} might be more appropriate.
+ */
+@Repeatable(BasedOnJDKFile.List.class)
+@Retention(RetentionPolicy.RUNTIME)
+@Target(value = {ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.METHOD})
+@Platforms(Platform.HOSTED_ONLY.class)
+public @interface BasedOnJDKFile {
+
+    /**
+     * Path to the source file relative to the repository root (usually
+     * <a href="https://github.com/openjdk/jdk">openjdk</a>). The path elements must be separated by
+     * slashes ({@code /}) and since it is a relative path, it must not start with a slash.
+     *
+     * To specify a line range, a suffix of the form {@code #L[0-9]+-L[0-9]+} might be added. Full
+     * example:
+     *
+     * <pre>
+     *     &#64;BasedOnJDKFile("src/hotspot/cpu/x86/vm_version_x86.hpp#L40-L304")
+     * </pre>
+     *
+     * The path and line numbers always apply to the latest supported JDK version. That version can
+     * be retrieved from the {@code jdks.oraclejdk-latest} entry from {@code common.json} in the
+     * root of this repository, or by looking up the latest version in the
+     * {@code JVMCI_MIN_VERSIONS} map in {@link jdk.graal.compiler.hotspot.JVMCIVersionCheck}. At
+     * the time of writing this is {@code jdk-23+8} (formatted as a git tag as used by the openjdk).
+     * That information can also be used to view the respective line range on GitHub via
+     * {@code https://github.com/openjdk/jdk/blob/<version-tag>/<value>}. For the example above, it
+     * would translate to <a href=
+     * "https://github.com/openjdk/jdk/blob/jdk-23+8/src/hotspot/cpu/x86/vm_version_x86.hpp#L40-L304">
+     * {@code https://github.com/openjdk/jdk/blob/jdk-23+8/src/hotspot/cpu/x86/vm_version_x86.hpp#L40-L304}</a>
+     */
+    String value();
+
+    /**
+     * Support for making {@link BasedOnJDKFile} {@linkplain Repeatable repeatable}.
+     */
+    @Retention(RetentionPolicy.RUNTIME)
+    @Target(value = {ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.METHOD})
+    @Platforms(Platform.HOSTED_ONLY.class)
+    @interface List {
+        BasedOnJDKFile[] value();
+    }
+}

substratevm/src/com.oracle.svm.processor/src/META-INF/services/javax.annotation.processing.Processor

@@ -1,2 +1,3 @@
 com.oracle.svm.processor.AutomaticallyRegisteredFeatureProcessor
 com.oracle.svm.processor.AutomaticallyRegisteredImageSingletonProcessor
+com.oracle.svm.processor.BasedOnJDKFileProcessor