Skip to content

[GR-65773] Integrate foreign configuration into reachability-metadata.json #11805

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 30, 2025
Merged

[GR-65773] Integrate foreign configuration into reachability-metadata.json #11805

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
144 changes: 0 additions & 144 deletions docs/reference-manual/native-image/assets/foreign-config-schema-v0.1.0.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,144 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://raw.githubusercontent.com/oracle/graal/master/docs/reference-manual/native-image/assets/foreign-config-schema-v0.1.0.json",
"properties": {
"downcalls": {
"default": [],
"items": {
"properties": {
"condition": {
"$ref": "config-condition-schema-v1.0.0.json",
"title": "Condition under which the downcall stub should be registered"
},
"returnType": {
"type": "string",
"title": "A memory layout definition (allows canonical layouts; see 'java.lang.foreign.Linker')"
},
"parameterTypes": {
"default": [],
"items": {
"type": "string",
"title": "A memory layout definition (allows canonical layouts; see 'java.lang.foreign.Linker')"
},
"type": "array",
"title": "List of the function descriptor's parameter types "
},
"options": {
"type": "object",
"title": "Linker options (see 'java.lang.foreign.Linker.Option')",
"properties": {
"captureCallState": {
"type": "boolean",
"title": "Specifies if a call state should be captured. Which states to capture is determined at run time. See also: 'java.lang.foreign.Linker.Option.captureCallState'"
},
"critical": {
"type": "object",
"title": "see 'java.lang.foreign.Linker.Option.critical'",
"properties": {
"allowHeapAccess": {
"type": "boolean"
}
},
"additionalProperties": false
},
"firstVariadicArg": {
"type": "integer",
"title": "see 'java.lang.foreign.Linker.Option.firstVariadicArg'"
}
},
"additionalProperties": false
}
},
"additionalProperties": false,
"type": "object",
"title": "A function descriptor to be registered for a downcall"
},
"type": "array",
"title": "List of function descriptors that should be registered for downcalls"
},
"upcalls": {
"default": [],
"items": {
"properties": {
"condition": {
"$ref": "config-condition-schema-v1.0.0.json",
"title": "Condition under which the upcall stub should be registered"
},
"returnType": {
"type": "string",
"title": "A memory layout definition (allows canonical layouts; see 'java.lang.foreign.Linker')"
},
"parameterTypes": {
"default": [],
"items": {
"type": "string",
"title": "A memory layout definition (allows canonical layouts; see 'java.lang.foreign.Linker')"
},
"type": "array",
"title": "List of the function descriptor's parameter types "
},
"options": {
"type": "object",
"title": "Linker options (see 'java.lang.foreign.Linker.Option')",
"description": "Currently, no linker options are allowed for upcalls. This may change in future.",
"properties": { },
"additionalProperties": false
}
},
"additionalProperties": false,
"type": "object",
"title": "A function descriptor to be registered for an upcall"
},
"type": "array",
"title": "List of function descriptors that should be registered for upcalls"
},
"directUpcalls": {
"default": [],
"items": {
"properties": {
"condition": {
"$ref": "config-condition-schema-v1.0.0.json",
"title": "Condition under which the direct upcall stub should be registered"
},
"class": {
"type": "string",
"title": "Full-qualified class name (e.g. 'org.package.OuterClass$InnerClass')"
},
"method": {
"type": "string",
"title": "Method name"
},
"returnType": {
"type": "string",
"title": "A memory layout definition (allows canonical layouts; see 'java.lang.foreign.Linker')"
},
"parameterTypes": {
"default": [],
"items": {
"type": "string",
"title": "A memory layout definition (allows canonical layouts; see 'java.lang.foreign.Linker')"
},
"type": "array",
"title": "List of the function descriptor's parameter types "
},
"options": {
"type": "object",
"title": "Linker options (see 'java.lang.foreign.Linker.Option')",
"description": "Currently, no linker options are allowed for direct upcalls. This may change in future.",
"properties": { },
"additionalProperties": false
}
},
"additionalProperties": false,
"type": "object",
"title": "A Java method and function descriptor to be registered for a direct upcall"
},
"type": "array",
"title": "List of Java methods and function descriptors that should be registered for direct upcalls"
}
},
"type": "object",
"additionalProperties": false,
"title": "JSON schema for the FFM API configuration that GraalVM Native Image uses",
"description": "A description and examples for writing an FFM API configuration can be found at https://github.com/oracle/graal/blob/master/docs/reference-manual/native-image/ForeignInterface.md"
}
164 changes: 153 additions & 11 deletions docs/reference-manual/native-image/assets/reachability-metadata-schema-v1.1.0.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -157,6 +157,148 @@
],
"additionalProperties": false
}
},
"foreign": {
"properties": {
"downcalls": {
"default": [],
"items": {
"properties": {
"condition": {
"$ref": "config-condition-schema-v1.0.0.json",
"title": "Condition under which the downcall stub should be registered"
},
"returnType": {
"type": "string",
"title": "Memory layout definition (allows canonical layouts; see `java.lang.foreign.Linker`)"
},
"parameterTypes": {
"default": [],
"items": {
"type": "string",
"title": "Memory layout definition (allows canonical layouts; see `java.lang.foreign.Linker`)"
},
"type": "array",
"title": "List of the function descriptor's parameter types"
},
"options": {
"type": "object",
"title": "Linker options (see `java.lang.foreign.Linker.Option`)",
"properties": {
"captureCallState": {
"type": "boolean",
"title": "Specifies whether a call state should be captured. The specific states to capture are determined at run time. See also: `java.lang.foreign.Linker.Option.captureCallState`"
},
"critical": {
"type": "object",
"title": "See `java.lang.foreign.Linker.Option.critical`",
"properties": {
"allowHeapAccess": {
"type": "boolean"
}
},
"additionalProperties": false
},
"firstVariadicArg": {
"type": "integer",
"title": "See `java.lang.foreign.Linker.Option.firstVariadicArg`"
}
},
"additionalProperties": false
}
},
"additionalProperties": false,
"type": "object",
"title": "Function descriptor to be registered for a downcall"
},
"type": "array",
"title": "List of function descriptors that should be registered for downcalls"
},
"upcalls": {
"default": [],
"items": {
"properties": {
"condition": {
"$ref": "config-condition-schema-v1.0.0.json",
"title": "Condition under which the upcall stub should be registered"
},
"returnType": {
"type": "string",
"title": "Memory layout definition (allows canonical layouts; see `java.lang.foreign.Linker`)"
},
"parameterTypes": {
"default": [],
"items": {
"type": "string",
"title": "Memory layout definition (allows canonical layouts; see `java.lang.foreign.Linker`)"
},
"type": "array",
"title": "List of the function descriptor's parameter types"
},
"options": {
"type": "object",
"title": "Linker options (see `java.lang.foreign.Linker.Option`)",
"description": "Currently, no linker options are allowed for upcalls. This may change in the future.",
"properties": { },
"additionalProperties": false
}
},
"additionalProperties": false,
"type": "object",
"title": "Function descriptor to be registered for an upcall"
},
"type": "array",
"title": "List of function descriptors that should be registered for upcalls"
},
"directUpcalls": {
"default": [],
"items": {
"properties": {
"condition": {
"$ref": "config-condition-schema-v1.0.0.json",
"title": "Condition under which the direct upcall stub should be registered"
},
"class": {
"type": "string",
"title": "Fully-qualified class name (e.g. `org.package.OuterClass$InnerClass`)"
},
"method": {
"type": "string",
"title": "Method name"
},
"returnType": {
"type": "string",
"title": "Memory layout definition (allows canonical layouts; see `java.lang.foreign.Linker`)"
},
"parameterTypes": {
"default": [],
"items": {
"type": "string",
"title": "Memory layout definition (allows canonical layouts; see `java.lang.foreign.Linker`)"
},
"type": "array",
"title": "List of the function descriptor's parameter types "
},
"options": {
"type": "object",
"title": "Linker options (see `java.lang.foreign.Linker.Option`)",
"description": "Currently, no linker options are allowed for direct upcalls. This may change in the future.",
"properties": { },
"additionalProperties": false
}
},
"additionalProperties": false,
"type": "object",
"title": "Java method and function descriptor to be registered for a direct upcall"
},
"type": "array",
"title": "List of Java methods and function descriptors that should be registered for direct upcalls"
}
},
"type": "object",
"additionalProperties": false,
"title": "JSON schema for the FFM API configuration used by GraalVM Native Image",
"description": "For a description and examples of writing an FFM API configuration, see: https://github.com/oracle/graal/blob/master/docs/reference-manual/native-image/ForeignInterface.md"
}
},
"required": [],
Expand Down Expand Up @@ -352,7 +494,7 @@
"type": "array",
"default": [],
"items": {
"title": "Fully qualified name of the interface defining the proxy class",
"title": "Fully-qualified name of the interface defining the proxy class",
"type": "string"
}
},
Expand All @@ -362,27 +504,27 @@
"properties": {
"declaringClass": {
"title": "The class in which the lambda class is defined",
"type": "#/$defs/type"
"$ref": "#/$defs/type"
},
"declaringMethod": {
"title": "The method in which the lambda class is defined",
"type": "#/$defs/method",
"$ref": "#/$defs/method",
"default": {}
},
"interfaces": {
"title": "Non-empty list of interfaces implemented by the lambda class",
"type": "array",
"items": {
"title": "Fully qualified name of the interface implemented by the lambda class",
"title": "Fully-qualified name of the interface implemented by the lambda class",
"type": "string"
}
},
"required": [
"declaringClass",
"interfaces"
],
"additionalProperties": false
}
}
},
"required": [
"declaringClass",
"interfaces"
],
"additionalProperties": false
}
},
"oneOf": [
Expand Down
1 change: 1 addition & 0 deletions substratevm/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ This changelog summarizes major changes to GraalVM Native Image.
Run-time initialization of security providers helps reduce image heap size by avoiding unnecessary objects inclusion.
* (GR-48191) Enable lambda classes to be registered for reflection and serialization in _reachability-metadata.json_. The format is detailed [here](https://github.com/oracle/graal/blob/master/docs/reference-manual/native-image/ReachabilityMetadata.md).
* (GR-54697) Parallelize debug info generation and add support for run-time debug info generation. `-H:+RuntimeDebugInfo` adds a run-time debug info generator into a native image for use with GDB.
* (GR-65773) Integrate Foreign Function and Memory (FFM) API metadata into _reachability-metadata.json_.

## GraalVM for JDK 24 (Internal Version 24.2.0)
* (GR-59717) Added `DuringSetupAccess.registerObjectReachabilityHandler` to allow registering a callback that is executed when an object of a specified type is marked as reachable during heap scanning.
Expand Down
2 changes: 1 addition & 1 deletion substratevm/src/com.oracle.svm.configure/src/com/oracle/svm/configure/ConfigurationFile.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ public enum ConfigurationFile {
DYNAMIC_PROXY("proxy", null, true, false),
PREDEFINED_CLASSES_NAME("predefined-classes", null, true, false),
/* Non-metadata categories */
FOREIGN("foreign", FOREIGN_KEY, true, false),
FOREIGN("foreign", FOREIGN_KEY, true, true),
SERIALIZATION_DENY("serialization-deny", null, false, false);

public static final String LEGACY_FILE_NAME_SUFFIX = "-config.json";
Expand Down
2 changes: 1 addition & 1 deletion ...ratevm/src/com.oracle.svm.configure/src/com/oracle/svm/configure/ConfigurationParser.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ public void parseAndRegister(Reader reader) throws IOException {

public Object getFromGlobalFile(Object json, String key) {
EconomicMap<String, Object> map = asMap(json, "top level of reachability metadata file must be an object");
checkAttributes(map, "reachability metadata", Collections.emptyList(), List.of(REFLECTION_KEY, JNI_KEY, SERIALIZATION_KEY, RESOURCES_KEY, BUNDLES_KEY, "reason", "comment"));
checkAttributes(map, "reachability metadata", Collections.emptyList(), List.of(REFLECTION_KEY, JNI_KEY, SERIALIZATION_KEY, RESOURCES_KEY, BUNDLES_KEY, FOREIGN_KEY, "reason", "comment"));
return map.get(key);
}

Expand Down
6 changes: 5 additions & 1 deletion ...src/com.oracle.svm.configure/src/com/oracle/svm/configure/ForeignConfigurationParser.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,11 @@ public ForeignConfigurationParser(EnumSet<ConfigurationParserOption> parserOptio

@Override
public void parseAndRegister(Object json, URI origin) {
var topLevel = asMap(json, "first level of document must be a map");
var foreignJson = getFromGlobalFile(json, FOREIGN_KEY);
if (foreignJson == null) {
return;
}
var topLevel = asMap(foreignJson, "first level of document must be a map");
checkAttributes(topLevel, "foreign methods categories", List.of(), List.of("downcalls", "upcalls", "directUpcalls"));

var downcalls = asList(topLevel.get("downcalls", List.of()), "downcalls must be an array of function descriptor and linker options");
Expand Down
Loading