Summary

Relax the specification of the foreign linker, to allow linker implementations to support additional layouts beyond the specified set such as 'packed' struct layouts.

Problem

During porting efforts of the FFM API to other platforms, it became clear that there are platforms out there that commonly require layouts beyond what the current specification allows.

More concretely, the AIX/PPC64 platform commonly uses a packed ABI, in which fields of the C double type, are aligned to 4 bytes within a struct if they are not the first member of a struct. The current linker specification however, forbids primitive layouts that are not aligned to their natural alignment. i.e. where the alignment is equal to the size of the type.

Solution

We relax the linker specification. The set of currently supported layouts becomes a minimal set of supported layouts.

Additionally, we add an extra note to say that more layouts beyond the minimal set may be supported by a linker implementation, such as packed struct layouts.

This will allow the AIX/PPC linker to support these packed struct layouts as well.

Specification

diff --git a/src/java.base/share/classes/java/lang/foreign/Linker.java b/src/java.base/share/classes/java/lang/foreign/Linker.java
index 738ff19a5170..5a5f2a0b8de9 100644
--- a/src/java.base/share/classes/java/lang/foreign/Linker.java
+++ b/src/java.base/share/classes/java/lang/foreign/Linker.java
@@ -224,8 +224,8 @@
  * </tbody>
  * </table></blockquote>
  * <p>
- * 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:
+ * All native linker implementations support a well-defined subset of 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 a canonical layout</li>
  * <li>{@code L} is a sequence layout {@code S} and all the following conditions hold:
@@ -244,6 +244,22 @@
  * </li>
  * </ul>
  *
+ * Linker implementations may optionally support additional layouts, such as <em>packed</em> struct layouts.
+ * A packed struct is a struct in which there is at least one member layout {@code L} that has an alignment
+ * constraint less strict than its natural alignment. This allows avoiding padding between member layouts,
+ * as well as avoiding padding at the end of the struct layout. For example:
+ * {@snippet lang = java:
+ * // No padding between the 2 element layouts:
+ * MemoryLayout noFieldPadding = MemoryLayout.structLayout(
+ *         ValueLayout.JAVA_INT,
+ *         ValueLayout.JAVA_DOUBLE.withByteAlignment(4));
+ *
+ * // No padding at the end of the struct:
+ * MemoryLayout noTrailingPadding = MemoryLayout.structLayout(
+ *         ValueLayout.JAVA_DOUBLE.withByteAlignment(4),
+ *         ValueLayout.JAVA_INT);
+ * }
+ * <p>
  * A native linker only supports function descriptors whose argument/return layouts are layouts supported by that linker
  * and are not sequence layouts.
  *