8308293: A linker should expose the layouts it supports

Reviewed-by: jvernee

Author: mcimadamore

src/java.base/share/classes/java/lang/foreign/Linker.java

@@ -31,12 +31,11 @@
 import jdk.internal.foreign.abi.SharedUtils;
 import jdk.internal.javac.PreviewFeature;
 import jdk.internal.reflect.CallerSensitive;
-import jdk.internal.reflect.Reflection;
 
 import java.lang.invoke.MethodHandle;
 import java.nio.ByteOrder;
+import java.util.Map;
 import java.util.Objects;
-import java.util.Optional;
 import java.util.Set;
 import java.util.function.Consumer;
 import java.util.stream.Collectors;
@@ -59,6 +58,12 @@
  * <li>A linker allows foreign functions to call Java method handles,
  * via the generation of {@linkplain #upcallStub(MethodHandle, FunctionDescriptor, Arena, Option...) upcall stubs}.</li>
  * </ul>
+ * A linker provides a way to look up the <em>canonical layouts</em> associated with the data types used by the ABI.
+ * For example, a linker implementing the C ABI might choose to provide a canonical layout for the C {@code size_t}
+ * type. On 64-bit platforms, this canonical layout might be equal to {@link ValueLayout#JAVA_LONG}. The canonical
+ * layouts supported by a linker are exposed via the {@link #canonicalLayouts()} method, which returns a map from
+ * type names to canonical layouts.
+ * <p>
  * In addition, a linker provides a way to look up foreign functions in libraries that conform to the ABI. Each linker
  * chooses a set of libraries that are commonly used on the OS and processor combination associated with the ABI.
  * For example, a linker for Linux/x64 might choose two libraries: {@code libc} and {@code libm}. The functions in these
@@ -103,11 +108,8 @@
  * defines the layouts associated with the parameter types and return type (if any) of the C function.
  * <p>
  * Scalar C types such as {@code bool}, {@code int} are modelled as {@linkplain ValueLayout value layouts}
- * of a suitable carrier. The mapping between a scalar type and its corresponding layout is dependent on the ABI
- * implemented by the native linker. For instance, the C type {@code long} maps to the layout constant
- * {@link ValueLayout#JAVA_LONG} on Linux/x64, but maps to the layout constant {@link ValueLayout#JAVA_INT} on
- * Windows/x64. Similarly, the C type {@code size_t} maps to the layout constant {@link ValueLayout#JAVA_LONG}
- * on 64-bit platforms, but maps to the layout constant {@link ValueLayout#JAVA_INT} on 32-bit platforms.
+ * of a suitable carrier. The {@linkplain #canonicalLayouts() mapping} between a scalar type and its corresponding
+ * canonical layout is dependent on the ABI implemented by the native linker (see below).
  * <p>
  * Composite types are modelled as {@linkplain GroupLayout group layouts}. More specifically, a C {@code struct} type
  * maps to a {@linkplain StructLayout struct layout}, whereas a C {@code union} type maps to a {@link UnionLayout union
@@ -122,7 +124,33 @@
  * a pointer that is known to point to a C {@code int[2]} array can be modelled as an address layout whose
  * target layout is a sequence layout whose element count is 2, and whose element type is {@link ValueLayout#JAVA_INT}.
  * <p>
- * The following table shows some examples of how C types are modelled in Linux/x64:
+ * All native linker implementations are guaranteed to provide canonical layouts for the following set of types:
+ * <ul>
+ *     <li>{@code bool}</li>
+ *     <li>{@code char}</li>
+ *     <li>{@code short}</li>
+ *     <li>{@code int}</li>
+ *     <li>{@code long}</li>
+ *     <li>{@code long long}</li>
+ *     <li>{@code float}</li>
+ *     <li>{@code double}</li>
+ *     <li>{@code size_t}</li>
+ *     <li>{@code wchar_t}</li>
+ *     <li>{@code void*}</li>
+ * </ul>
+ * As noted above, the specific canonical layout associated with each type can vary, depending on the data model
+ * supported by a given ABI. For instance, the C type {@code long} maps to the layout constant {@link ValueLayout#JAVA_LONG}
+ * on Linux/x64, but maps to the layout constant {@link ValueLayout#JAVA_INT} on Windows/x64. Similarly, the C type
+ * {@code size_t} maps to the layout constant {@link ValueLayout#JAVA_LONG} on 64-bit platforms, but maps to the layout
+ * constant {@link ValueLayout#JAVA_INT} on 32-bit platforms.
+ * <p>
+ * A native linker typically does not provide canonical layouts for C's unsigned integral types. Instead, they are
+ * modelled using the canonical layouts associated with their corresponding signed integral types. For instance,
+ * the C type {@code unsigned long} maps to the layout constant {@link ValueLayout#JAVA_LONG} on Linux/x64, but maps to
+ * the layout constant {@link ValueLayout#JAVA_INT} on Windows/x64.
+ * <p>
+ * The following table shows some examples of how C types are modelled in Linux/x64 (all the examples provided
+ * here will assume these platform-dependent mappings):
  *
  * <blockquote><table class="plain">
  * <caption style="display:none">Mapping C types</caption>
@@ -137,19 +165,19 @@
  * <tr><th scope="row" style="font-weight:normal">{@code bool}</th>
  *     <td style="text-align:center;">{@link ValueLayout#JAVA_BOOLEAN}</td>
  *     <td style="text-align:center;">{@code boolean}</td>
- * <tr><th scope="row" style="font-weight:normal">{@code char}</th>
+ * <tr><th scope="row" style="font-weight:normal">{@code char} <br> {@code unsigned char}</th>
  *     <td style="text-align:center;">{@link ValueLayout#JAVA_BYTE}</td>
  *     <td style="text-align:center;">{@code byte}</td>
- * <tr><th scope="row" style="font-weight:normal">{@code short}</th>
+ * <tr><th scope="row" style="font-weight:normal">{@code short} <br> {@code unsigned short}</th>
  *     <td style="text-align:center;">{@link ValueLayout#JAVA_SHORT}</td>
  *     <td style="text-align:center;">{@code short}</td>
- * <tr><th scope="row" style="font-weight:normal">{@code int}</th>
+ * <tr><th scope="row" style="font-weight:normal">{@code int} <br> {@code unsigned int}</th>
  *     <td style="text-align:center;">{@link ValueLayout#JAVA_INT}</td>
  *     <td style="text-align:center;">{@code int}</td>
- * <tr><th scope="row" style="font-weight:normal">{@code long}</th>
+ * <tr><th scope="row" style="font-weight:normal">{@code long} <br> {@code unsigned long}</th>
  *     <td style="text-align:center;">{@link ValueLayout#JAVA_LONG}</td>
  *     <td style="text-align:center;">{@code long}</td>
- * <tr><th scope="row" style="font-weight:normal">{@code long long}</th>
+ * <tr><th scope="row" style="font-weight:normal">{@code long long} <br> {@code unsigned long long}</th>
  *     <td style="text-align:center;">{@link ValueLayout#JAVA_LONG}</td>
  *     <td style="text-align:center;">{@code long}</td>
  * <tr><th scope="row" style="font-weight:normal">{@code float}</th>
@@ -200,20 +228,7 @@
  * All native linker implementations operate on a subset of memory layouts. More formally, a layout {@code L}
  * is supported by a native linker {@code NL} if:
  * <ul>
- * <li>{@code L} is a value layout {@code V} and {@code V.withoutName()} is {@linkplain MemoryLayout#equals(Object) equal}
- * to one of the following layout constants:
- * <ul>
- * <li>{@link ValueLayout#JAVA_BOOLEAN}</li>
- * <li>{@link ValueLayout#JAVA_BYTE}</li>
- * <li>{@link ValueLayout#JAVA_CHAR}</li>
- * <li>{@link ValueLayout#JAVA_SHORT}</li>
- * <li>{@link ValueLayout#JAVA_INT}</li>
- * <li>{@link ValueLayout#JAVA_LONG}</li>
- * <li>{@link ValueLayout#JAVA_FLOAT}</li>
- * <li>{@link ValueLayout#JAVA_DOUBLE}</li>
- * </ul></li>
- * <li>{@code L} is an address layout {@code A} and {@code A.withoutTargetLayout().withoutName()} is
- * {@linkplain MemoryLayout#equals(Object) equal} to {@link ValueLayout#ADDRESS}</li>
+ * <li>{@code L} is a value layout {@code V} and {@code V.withoutName()} is a canonical layout</li>
  * <li>{@code L} is a sequence layout {@code S} and all the following conditions hold:
  * <ol>
  * <li>the alignment constraint of {@code S} is set to its <a href="MemoryLayout.html#layout-align">natural alignment</a>, and</li>
@@ -492,6 +507,8 @@ public sealed interface Linker permits AbstractLinker {
      * is the combination of OS and processor where the Java runtime is currently executing.
      *
      * @apiNote It is not currently possible to obtain a linker for a different combination of OS and processor.
+     * @implSpec A native linker implementation is guaranteed to provide canonical layouts for
+     * <a href="#describing-c-sigs">basic C types</a>.
      * @implNote The libraries exposed by the {@linkplain #defaultLookup() default lookup} associated with the returned
      * linker are the native libraries loaded in the process where the Java runtime is currently executing. For example,
      * on Linux, these libraries typically include {@code libc}, {@code libm} and {@code libdl}.
@@ -635,6 +652,22 @@ static Linker nativeLinker() {
      */
     SymbolLookup defaultLookup();
 
+    /**
+     * {@return an unmodifiable mapping between the names of data types used by the ABI implemented by this linker and their
+     * <em>canonical layouts</em>}
+     * <p>
+     * Each {@link Linker} is responsible for choosing the data types that are widely recognized as useful on the OS
+     * and processor combination supported by the {@link Linker}. Accordingly, the precise set of data type names
+     * and canonical layouts exposed by the linker is unspecified; it varies from one {@link Linker} to another.
+     * @implNote It is strongly recommended that the result of {@link #canonicalLayouts()} exposes a set of symbols that is stable over time.
+     * Clients of {@link #canonicalLayouts()} are likely to fail if a data type that was previously exposed by the linker
+     * is no longer exposed, or if its canonical layout is updated.
+     * <p>If an implementer provides {@link Linker} implementations for multiple OS and processor combinations, then it is strongly
+     * recommended that the result of {@link #canonicalLayouts()} exposes, as much as possible, a consistent set of symbols
+     * across all the OS and processor combinations.
+     */
+    Map<String, MemoryLayout> canonicalLayouts();
+
     /**
      * A linker option is used to provide additional parameters to a linkage request.
      * @since 20

src/java.base/share/classes/jdk/internal/foreign/abi/AbstractLinker.java

@@ -52,6 +52,7 @@
 import java.lang.foreign.ValueLayout;
 import java.lang.invoke.MethodHandle;
 import java.lang.invoke.MethodType;
+import java.util.HashSet;
 import java.util.List;
 import java.nio.ByteOrder;
 import java.util.Objects;
@@ -69,6 +70,7 @@ public interface UpcallStubFactory {
     private record LinkRequest(FunctionDescriptor descriptor, LinkerOptions options) {}
     private final SoftReferenceCache<LinkRequest, MethodHandle> DOWNCALL_CACHE = new SoftReferenceCache<>();
     private final SoftReferenceCache<LinkRequest, UpcallStubFactory> UPCALL_CACHE = new SoftReferenceCache<>();
+    private final Set<MemoryLayout> CANONICAL_LAYOUTS_CACHE = new HashSet<>(canonicalLayouts().values());
 
     @Override
     @CallerSensitive
@@ -209,7 +211,7 @@ private void checkLayoutRecursive(MemoryLayout layout) {
     }
 
     // check for trailing padding
-    private static void checkGroupSize(GroupLayout gl, long maxUnpaddedOffset) {
+    private void checkGroupSize(GroupLayout gl, long maxUnpaddedOffset) {
         long expectedSize = Utils.alignUp(maxUnpaddedOffset, gl.byteAlignment());
         if (gl.byteSize() != expectedSize) {
             throw new IllegalArgumentException("Layout '" + gl + "' has unexpected size: "
@@ -219,7 +221,7 @@ private static void checkGroupSize(GroupLayout gl, long maxUnpaddedOffset) {
 
     // checks both that there is no excess padding between 'memberLayout' and
     // the previous layout
-    private static void checkMemberOffset(StructLayout parent, MemoryLayout memberLayout,
+    private void checkMemberOffset(StructLayout parent, MemoryLayout memberLayout,
                                           long lastUnpaddedOffset, long offset) {
         long expectedOffset = Utils.alignUp(lastUnpaddedOffset, memberLayout.byteAlignment());
         if (expectedOffset != offset) {
@@ -228,17 +230,17 @@ private static void checkMemberOffset(StructLayout parent, MemoryLayout memberLa
         }
     }
 
-    private static void checkSupported(ValueLayout valueLayout) {
+    private void checkSupported(ValueLayout valueLayout) {
         valueLayout = valueLayout.withoutName();
         if (valueLayout instanceof AddressLayout addressLayout) {
             valueLayout = addressLayout.withoutTargetLayout();
         }
-        if (!SUPPORTED_LAYOUTS.contains(valueLayout.withoutName())) {
+        if (!CANONICAL_LAYOUTS_CACHE.contains(valueLayout.withoutName())) {
             throw new IllegalArgumentException("Unsupported layout: " + valueLayout);
         }
     }
 
-    private static void checkHasNaturalAlignment(MemoryLayout layout) {
+    private void checkHasNaturalAlignment(MemoryLayout layout) {
         if (!((AbstractLayout<?>) layout).hasNaturalAlignment()) {
             throw new IllegalArgumentException("Layout alignment must be natural alignment: " + layout);
         }
@@ -269,16 +271,4 @@ private static FunctionDescriptor stripNames(FunctionDescriptor function) {
                 .map(rl -> FunctionDescriptor.of(stripNames(rl), stripNames(function.argumentLayouts())))
                 .orElseGet(() -> FunctionDescriptor.ofVoid(stripNames(function.argumentLayouts())));
     }
-
-    private static final Set<MemoryLayout> SUPPORTED_LAYOUTS = Set.of(
-            ValueLayout.JAVA_BOOLEAN,
-            ValueLayout.JAVA_BYTE,
-            ValueLayout.JAVA_CHAR,
-            ValueLayout.JAVA_SHORT,
-            ValueLayout.JAVA_INT,
-            ValueLayout.JAVA_FLOAT,
-            ValueLayout.JAVA_LONG,
-            ValueLayout.JAVA_DOUBLE,
-            ValueLayout.ADDRESS
-    );
 }

src/java.base/share/classes/jdk/internal/foreign/abi/SharedUtils.java

@@ -493,4 +493,35 @@ static Object read(MemorySegment ptr, long offset, Class<?> type) {
             throw new IllegalArgumentException("Unsupported carrier: " + type);
         }
     }
+
+    public static Map<String, MemoryLayout> canonicalLayouts(ValueLayout longLayout, ValueLayout sizetLayout, ValueLayout wchartLayout) {
+        return Map.ofEntries(
+                // specified canonical layouts
+                Map.entry("bool", ValueLayout.JAVA_BOOLEAN),
+                Map.entry("char", ValueLayout.JAVA_BYTE),
+                Map.entry("short", ValueLayout.JAVA_SHORT),
+                Map.entry("int", ValueLayout.JAVA_INT),
+                Map.entry("float", ValueLayout.JAVA_FLOAT),
+                Map.entry("long", longLayout),
+                Map.entry("long long", ValueLayout.JAVA_LONG),
+                Map.entry("double", ValueLayout.JAVA_DOUBLE),
+                Map.entry("void*", ValueLayout.ADDRESS),
+                Map.entry("size_t", sizetLayout),
+                Map.entry("wchar_t", wchartLayout),
+                // unspecified size-dependent layouts
+                Map.entry("int8_t", ValueLayout.JAVA_BYTE),
+                Map.entry("int16_t", ValueLayout.JAVA_SHORT),
+                Map.entry("int32_t", ValueLayout.JAVA_INT),
+                Map.entry("int64_t", ValueLayout.JAVA_LONG),
+                // unspecified JNI layouts
+                Map.entry("jboolean", ValueLayout.JAVA_BOOLEAN),
+                Map.entry("jchar", ValueLayout.JAVA_CHAR),
+                Map.entry("jbyte", ValueLayout.JAVA_BYTE),
+                Map.entry("jshort", ValueLayout.JAVA_SHORT),
+                Map.entry("jint", ValueLayout.JAVA_INT),
+                Map.entry("jlong", ValueLayout.JAVA_LONG),
+                Map.entry("jfloat", ValueLayout.JAVA_FLOAT),
+                Map.entry("jdouble", ValueLayout.JAVA_DOUBLE)
+        );
+    }
 }

src/java.base/share/classes/jdk/internal/foreign/abi/aarch64/linux/LinuxAArch64Linker.java

@@ -27,19 +27,26 @@
 
 import jdk.internal.foreign.abi.AbstractLinker;
 import jdk.internal.foreign.abi.LinkerOptions;
+import jdk.internal.foreign.abi.SharedUtils;
 import jdk.internal.foreign.abi.aarch64.CallArranger;
 
 import java.lang.foreign.FunctionDescriptor;
+import java.lang.foreign.MemoryLayout;
+import java.lang.foreign.ValueLayout;
 import java.lang.invoke.MethodHandle;
 import java.lang.invoke.MethodType;
 import java.nio.ByteOrder;
+import java.util.Map;
 
 /**
  * ABI implementation based on ARM document "Procedure Call Standard for
  * the ARM 64-bit Architecture".
  */
 public final class LinuxAArch64Linker extends AbstractLinker {
 
+    static final Map<String, MemoryLayout> CANONICAL_LAYOUTS =
+            SharedUtils.canonicalLayouts(ValueLayout.JAVA_LONG, ValueLayout.JAVA_LONG, ValueLayout.JAVA_INT);
+
     public static LinuxAArch64Linker getInstance() {
         final class Holder {
             private static final LinuxAArch64Linker INSTANCE = new LinuxAArch64Linker();
@@ -66,4 +73,9 @@ protected UpcallStubFactory arrangeUpcall(MethodType targetType, FunctionDescrip
     protected ByteOrder linkerByteOrder() {
         return ByteOrder.LITTLE_ENDIAN;
     }
+
+    @Override
+    public Map<String, MemoryLayout> canonicalLayouts() {
+        return CANONICAL_LAYOUTS;
+    }
 }

src/java.base/share/classes/jdk/internal/foreign/abi/aarch64/macos/MacOsAArch64Linker.java

@@ -27,19 +27,26 @@
 
 import jdk.internal.foreign.abi.AbstractLinker;
 import jdk.internal.foreign.abi.LinkerOptions;
+import jdk.internal.foreign.abi.SharedUtils;
 import jdk.internal.foreign.abi.aarch64.CallArranger;
 
 import java.lang.foreign.FunctionDescriptor;
+import java.lang.foreign.MemoryLayout;
+import java.lang.foreign.ValueLayout;
 import java.lang.invoke.MethodHandle;
 import java.lang.invoke.MethodType;
 import java.nio.ByteOrder;
+import java.util.Map;
 
 /**
  * ABI implementation for macOS on Apple silicon. Based on AAPCS with
  * changes to va_list and passing arguments on the stack.
  */
 public final class MacOsAArch64Linker extends AbstractLinker {
 
+    static final Map<String, MemoryLayout> CANONICAL_LAYOUTS =
+            SharedUtils.canonicalLayouts(ValueLayout.JAVA_LONG, ValueLayout.JAVA_LONG, ValueLayout.JAVA_INT);
+
     public static MacOsAArch64Linker getInstance() {
         final class Holder {
             private static final MacOsAArch64Linker INSTANCE = new MacOsAArch64Linker();
@@ -66,4 +73,9 @@ protected UpcallStubFactory arrangeUpcall(MethodType targetType, FunctionDescrip
     protected ByteOrder linkerByteOrder() {
         return ByteOrder.LITTLE_ENDIAN;
     }
+
+    @Override
+    public Map<String, MemoryLayout> canonicalLayouts() {
+        return CANONICAL_LAYOUTS;
+    }
 }

src/java.base/share/classes/jdk/internal/foreign/abi/aarch64/windows/WindowsAArch64Linker.java

@@ -28,18 +28,25 @@
 
 import jdk.internal.foreign.abi.AbstractLinker;
 import jdk.internal.foreign.abi.LinkerOptions;
+import jdk.internal.foreign.abi.SharedUtils;
 import jdk.internal.foreign.abi.aarch64.CallArranger;
 
 import java.lang.foreign.FunctionDescriptor;
+import java.lang.foreign.MemoryLayout;
+import java.lang.foreign.ValueLayout;
 import java.lang.invoke.MethodHandle;
 import java.lang.invoke.MethodType;
 import java.nio.ByteOrder;
+import java.util.Map;
 
 /**
  * ABI implementation for Windows/AArch64. Based on AAPCS with
  * changes to va_list.
  */
 public final class WindowsAArch64Linker extends AbstractLinker {
+
+    static final Map<String, MemoryLayout> CANONICAL_LAYOUTS =
+            SharedUtils.canonicalLayouts(ValueLayout.JAVA_INT, ValueLayout.JAVA_LONG, ValueLayout.JAVA_CHAR);
     private static WindowsAArch64Linker instance;
 
     public static WindowsAArch64Linker getInstance() {
@@ -63,4 +70,9 @@ protected UpcallStubFactory arrangeUpcall(MethodType targetType, FunctionDescrip
     protected ByteOrder linkerByteOrder() {
         return ByteOrder.LITTLE_ENDIAN;
     }
+
+    @Override
+    public Map<String, MemoryLayout> canonicalLayouts() {
+        return CANONICAL_LAYOUTS;
+    }
 }