Skip to content

Conversation

@graalvmbot
Copy link
Collaborator

Implements a new, more user-friendly FFM API configuration file syntax.
Before this change, the configuration file syntax was based on the reverse-engineered toString representation of the function descriptors and memory layouts which turned out to be very tricky to use.

We therefore decided to introduce a syntax that aligns with the MemoryLayout factory methods.
The configuration file is still a JSON file. We now use a more JSON-style way to define a function descriptor:

{
  "downcalls": [
    { "returnType": "Layout", "parameterTypes": ["Layout", "Layout"] },
  ]
}

The syntax for a single returnType or parameterType is:

 Layout ::= Alignment | StructLayout | UnionLayout | SequenceLayout | ValueLayout | PaddingLayout
 Alignment ::= 'align' '(' Int ',' Layout ')'
 StructLayout ::= 'struct' '(' Layout* ')'
 UnionLayout ::=  'union' '(' Layout* ')'
 SequenceLayout ::= 'sequence' '(' Int ',' Layout ')'
 ValueLayout ::=  canonical layout (e.g. 'int', 'long', ...)
 PaddingLayout ::= 'padding' '(' Int ')'
 Int ::= a positive decimal integer

Example:

{ 
    "returnType":  "double", 
    "parameterTypes": ["sequence(10, long)", "struct(long, padding(8), long)", "union(int, double)"] 
}

Furthermore, for direct upcalls it is now possible to skip declaration of returnType and parameterTypes if the Java signature can be represented as FunctionDescriptor without ambiguity. This is the case if the Java signature does not contain any MemorySegment parameter or return type. For example:

Java:

public class MyClass {
    public static int foo(long x) {
        // ...
    }
    
    public static int foo(double x) {
        // ...
    }
}

Configuration File:

{
  "directUpcalls": [
    { "class", "MyClass", "method": "foo" },
  ]
}

This will register both overloads of MyClass.foo for direct upcalls.

An appropriate update of the docs (i.e. ForeignInterface.md) will follow in a separate PR.

@oracle-contributor-agreement oracle-contributor-agreement bot added the OCA Verified All contributors have signed the Oracle Contributor Agreement. label Apr 10, 2025
@graalvmbot graalvmbot force-pushed the fa/GR-60209/foreign_conf_file_syntax branch 2 times, most recently from 2c1fd55 to 5e85f05 Compare April 11, 2025 17:33
@graalvmbot graalvmbot force-pushed the fa/GR-60209/foreign_conf_file_syntax branch from 5e85f05 to 9d7699d Compare April 11, 2025 20:03
@graalvmbot graalvmbot closed this Apr 12, 2025
@graalvmbot graalvmbot deleted the fa/GR-60209/foreign_conf_file_syntax branch April 12, 2025 02:34
@graalvmbot graalvmbot merged commit 272457e into master Apr 12, 2025
12 of 13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

OCA Verified All contributors have signed the Oracle Contributor Agreement.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants