canonical path for intrinsics

This commit is contained in:
2026-03-24 13:42:37 +00:00
parent 59e33d6639
commit b33dc7c18d
11 changed files with 677 additions and 738 deletions
@@ -0,0 +1,142 @@
package p.studio.compiler.backend.irvm;
import java.util.Objects;
enum IRVMIntrinsicDefinition {
VEC2_DOT("vec2.dot", 1, 0x1000, "vec2", "dot", 4, 1, "float|float|float|float", "float", true, false),
VEC2_LENGTH("vec2.length", 1, 0x1001, "vec2", "length", 2, 1, "float|float", "float", true, false),
INPUT_PAD("input.pad", 1, 0x2000, "input", "pad", 0, 1, "", "builtin:input.pad", true, false),
INPUT_TOUCH("input.touch", 1, 0x2001, "input", "touch", 0, 1, "", "builtin:input.touch", true, false),
INPUT_PAD_UP("input.pad.up", 1, 0x2010, "input.pad", "up", 1, 1, "builtin:input.pad", "builtin:input.button", true, false),
INPUT_PAD_DOWN("input.pad.down", 1, 0x2011, "input.pad", "down", 1, 1, "builtin:input.pad", "builtin:input.button", true, false),
INPUT_PAD_LEFT("input.pad.left", 1, 0x2012, "input.pad", "left", 1, 1, "builtin:input.pad", "builtin:input.button", true, false),
INPUT_PAD_RIGHT("input.pad.right", 1, 0x2013, "input.pad", "right", 1, 1, "builtin:input.pad", "builtin:input.button", true, false),
INPUT_PAD_A("input.pad.a", 1, 0x2014, "input.pad", "a", 1, 1, "builtin:input.pad", "builtin:input.button", true, false),
INPUT_PAD_B("input.pad.b", 1, 0x2015, "input.pad", "b", 1, 1, "builtin:input.pad", "builtin:input.button", true, false),
INPUT_PAD_X("input.pad.x", 1, 0x2016, "input.pad", "x", 1, 1, "builtin:input.pad", "builtin:input.button", true, false),
INPUT_PAD_Y("input.pad.y", 1, 0x2017, "input.pad", "y", 1, 1, "builtin:input.pad", "builtin:input.button", true, false),
INPUT_PAD_L("input.pad.l", 1, 0x2018, "input.pad", "l", 1, 1, "builtin:input.pad", "builtin:input.button", true, false),
INPUT_PAD_R("input.pad.r", 1, 0x2019, "input.pad", "r", 1, 1, "builtin:input.pad", "builtin:input.button", true, false),
INPUT_PAD_START("input.pad.start", 1, 0x201A, "input.pad", "start", 1, 1, "builtin:input.pad", "builtin:input.button", true, false),
INPUT_PAD_SELECT("input.pad.select", 1, 0x201B, "input.pad", "select", 1, 1, "builtin:input.pad", "builtin:input.button", true, false),
INPUT_TOUCH_BUTTON("input.touch.button", 1, 0x2020, "input.touch", "button", 1, 1, "builtin:input.touch", "builtin:input.button", true, false),
INPUT_TOUCH_X("input.touch.x", 1, 0x2021, "input.touch", "x", 1, 1, "builtin:input.touch", "int", true, false),
INPUT_TOUCH_Y("input.touch.y", 1, 0x2022, "input.touch", "y", 1, 1, "builtin:input.touch", "int", true, false),
INPUT_BUTTON_PRESSED("input.button.pressed", 1, 0x2030, "input.button", "pressed", 1, 1, "builtin:input.button", "bool", true, false),
INPUT_BUTTON_RELEASED("input.button.released", 1, 0x2031, "input.button", "released", 1, 1, "builtin:input.button", "bool", true, false),
INPUT_BUTTON_DOWN("input.button.down", 1, 0x2032, "input.button", "down", 1, 1, "builtin:input.button", "bool", true, false),
INPUT_BUTTON_HOLD("input.button.hold", 1, 0x2033, "input.button", "hold", 1, 1, "builtin:input.button", "int", true, false);
private final String canonicalName;
private final long canonicalVersion;
private final int finalId;
private final String owner;
private final String name;
private final int argSlots;
private final int retSlots;
private final String argLayout;
private final String retLayout;
private final boolean deterministic;
private final boolean mayAllocate;
IRVMIntrinsicDefinition(
final String canonicalName,
final long canonicalVersion,
final int finalId,
final String owner,
final String name,
final int argSlots,
final int retSlots,
final String argLayout,
final String retLayout,
final boolean deterministic,
final boolean mayAllocate) {
this.canonicalName = requireNonBlank(canonicalName, "canonicalName");
this.canonicalVersion = requireNonNegative(canonicalVersion, "canonicalVersion");
this.finalId = finalId;
this.owner = requireNonBlank(owner, "owner");
this.name = requireNonBlank(name, "name");
this.argSlots = requireNonNegative(argSlots, "argSlots");
this.retSlots = requireNonNegative(retSlots, "retSlots");
this.argLayout = Objects.requireNonNull(argLayout, "argLayout");
this.retLayout = Objects.requireNonNull(retLayout, "retLayout");
this.deterministic = deterministic;
this.mayAllocate = mayAllocate;
}
String canonicalName() {
return canonicalName;
}
long canonicalVersion() {
return canonicalVersion;
}
int finalId() {
return finalId;
}
String owner() {
return owner;
}
String intrinsicName() {
return name;
}
int argSlots() {
return argSlots;
}
int retSlots() {
return retSlots;
}
String argLayout() {
return argLayout;
}
String retLayout() {
return retLayout;
}
boolean deterministic() {
return deterministic;
}
boolean mayAllocate() {
return mayAllocate;
}
String canonicalIdentity() {
return canonicalName + "@" + canonicalVersion;
}
private static String requireNonBlank(
final String value,
final String fieldName) {
final var normalized = Objects.requireNonNull(value, fieldName);
if (normalized.isBlank()) {
throw new IllegalArgumentException(fieldName + " must not be blank");
}
return normalized;
}
private static int requireNonNegative(
final int value,
final String fieldName) {
if (value < 0) {
throw new IllegalArgumentException(fieldName + " must be non-negative");
}
return value;
}
private static long requireNonNegative(
final long value,
final String fieldName) {
if (value < 0) {
throw new IllegalArgumentException(fieldName + " must be non-negative");
}
return value;
}
}
@@ -1,15 +1,10 @@
package p.studio.compiler.backend.irvm;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.Map;
import java.util.OptionalInt;
final class IRVMIntrinsicRegistry {
private static final String REGISTRY_RESOURCE = "/intrinsics/registry-v1.csv";
private static final Map<IntrinsicKey, Integer> FINAL_ID_BY_INTRINSIC = loadRegistry();
private IRVMIntrinsicRegistry() {
@@ -37,77 +32,28 @@ final class IRVMIntrinsicRegistry {
}
private static Map<IntrinsicKey, Integer> loadRegistry() {
final var stream = IRVMIntrinsicRegistry.class.getResourceAsStream(REGISTRY_RESOURCE);
if (stream == null) {
throw new IllegalStateException("missing intrinsic registry resource: " + REGISTRY_RESOURCE);
}
final var registry = new HashMap<IntrinsicKey, Integer>();
final var identityByFinalId = new HashMap<Integer, String>();
try (final var reader = new BufferedReader(new InputStreamReader(stream, StandardCharsets.UTF_8))) {
String rawLine;
int lineNumber = 0;
Integer previousFinalId = null;
while ((rawLine = reader.readLine()) != null) {
lineNumber++;
final var line = rawLine.trim();
if (line.isBlank() || line.startsWith("#")) {
continue;
}
final var columns = line.split(",", -1);
if (columns.length != 3) {
throw new IllegalStateException("invalid intrinsic registry row at line " + lineNumber + ": " + line);
}
final var canonicalName = columns[0].trim();
final long canonicalVersion;
try {
canonicalVersion = Long.parseLong(columns[1].trim());
} catch (NumberFormatException ex) {
throw new IllegalStateException("invalid intrinsic version at line " + lineNumber + ": " + line, ex);
}
if (canonicalName.isBlank()) {
throw new IllegalStateException("blank intrinsic name at line " + lineNumber + ": " + line);
}
if (canonicalVersion < 0) {
throw new IllegalStateException("negative intrinsic version at line " + lineNumber + ": " + line);
}
final int finalId = parseFinalId(columns[2].trim(), lineNumber, line);
if (previousFinalId != null && Integer.compareUnsigned(finalId, previousFinalId) <= 0) {
throw new IllegalStateException(
"intrinsic final ids must be strictly increasing for deterministic evolution at line "
+ lineNumber + ": " + line);
}
register(registry, canonicalName, canonicalVersion, finalId);
final var identity = canonicalIdentity(canonicalName, canonicalVersion);
final var previous = identityByFinalId.putIfAbsent(finalId, identity);
if (previous != null && !previous.equals(identity)) {
throw new IllegalStateException(
"duplicate intrinsic final id 0x%08X for %s and %s".formatted(finalId, previous, identity));
}
previousFinalId = finalId;
Integer previousFinalId = null;
for (final var definition : IRVMIntrinsicDefinition.values()) {
final var finalId = definition.finalId();
if (previousFinalId != null && Integer.compareUnsigned(finalId, previousFinalId) <= 0) {
throw new IllegalStateException(
"intrinsic final ids must be strictly increasing for deterministic evolution: "
+ definition.canonicalIdentity());
}
} catch (IOException ex) {
throw new IllegalStateException("failed to read intrinsic registry resource: " + REGISTRY_RESOURCE, ex);
register(registry, definition.canonicalName(), definition.canonicalVersion(), finalId);
final var identity = definition.canonicalIdentity();
final var previous = identityByFinalId.putIfAbsent(finalId, identity);
if (previous != null && !previous.equals(identity)) {
throw new IllegalStateException(
"duplicate intrinsic final id 0x%08X for %s and %s".formatted(finalId, previous, identity));
}
previousFinalId = finalId;
}
return Map.copyOf(registry);
}
private static int parseFinalId(
final String rawId,
final int lineNumber,
final String line) {
try {
if (rawId.startsWith("0x") || rawId.startsWith("0X")) {
return Integer.parseUnsignedInt(rawId.substring(2), 16);
}
return Integer.parseUnsignedInt(rawId, 10);
} catch (NumberFormatException ex) {
throw new IllegalStateException(
"invalid intrinsic final id at line %d: %s".formatted(lineNumber, line),
ex);
}
}
private static String canonicalIdentity(
final String canonicalName,
final long canonicalVersion) {
@@ -1,24 +0,0 @@
# canonicalName,canonicalVersion,finalId
vec2.dot,1,0x1000
vec2.length,1,0x1001
input.pad,1,0x2000
input.touch,1,0x2001
input.pad.up,1,0x2010
input.pad.down,1,0x2011
input.pad.left,1,0x2012
input.pad.right,1,0x2013
input.pad.a,1,0x2014
input.pad.b,1,0x2015
input.pad.x,1,0x2016
input.pad.y,1,0x2017
input.pad.l,1,0x2018
input.pad.r,1,0x2019
input.pad.start,1,0x201A
input.pad.select,1,0x201B
input.touch.button,1,0x2020
input.touch.x,1,0x2021
input.touch.y,1,0x2022
input.button.pressed,1,0x2030
input.button.released,1,0x2031
input.button.down,1,0x2032
input.button.hold,1,0x2033
1 # canonicalName canonicalVersion finalId
2 vec2.dot 1 0x1000
3 vec2.length 1 0x1001
4 input.pad 1 0x2000
5 input.touch 1 0x2001
6 input.pad.up 1 0x2010
7 input.pad.down 1 0x2011
8 input.pad.left 1 0x2012
9 input.pad.right 1 0x2013
10 input.pad.a 1 0x2014
11 input.pad.b 1 0x2015
12 input.pad.x 1 0x2016
13 input.pad.y 1 0x2017
14 input.pad.l 1 0x2018
15 input.pad.r 1 0x2019
16 input.pad.start 1 0x201A
17 input.pad.select 1 0x201B
18 input.touch.button 1 0x2020
19 input.touch.x 1 0x2021
20 input.touch.y 1 0x2022
21 input.button.pressed 1 0x2030
22 input.button.released 1 0x2031
23 input.button.down 1 0x2032
24 input.button.hold 1 0x2033
@@ -7,17 +7,21 @@ import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Locale;
import java.util.regex.Pattern;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.junit.jupiter.api.Assertions.fail;
class IRVMIntrinsicRegistryParityTest {
private static final Path RUNTIME_INTRINSICS_FILE = Path.of("../runtime/crates/console/prometeu-vm/src/builtins.rs");
private static final String VM_ARCH_INTRINSICS_PATH = "docs/vm-arch/INTRINSICS.csv";
private static final String RUNTIME_INTRINSICS_PATH = "crates/console/prometeu-vm/src/builtins.rs";
private static final Pattern OWNER_PATTERN = Pattern.compile("owner:\\s*\"([^\"]+)\",");
private static final Pattern NAME_PATTERN = Pattern.compile("name:\\s*\"([^\"]+)\",");
private static final Pattern VERSION_PATTERN = Pattern.compile("version:\\s*(\\d+),");
@@ -25,7 +29,7 @@ class IRVMIntrinsicRegistryParityTest {
private static final String STRICT_PARITY_ENV = "PROMETEU_INTRINSIC_PARITY_STRICT";
@Test
void registryResourceMustExposeExpectedCanonicalEntries() {
void registryDefinitionsMustExposeExpectedCanonicalEntries() {
final var snapshot = IRVMIntrinsicRegistry.snapshotByCanonicalIdentity();
assertFalse(snapshot.isEmpty());
assertEquals(23, snapshot.size());
@@ -33,19 +37,69 @@ class IRVMIntrinsicRegistryParityTest {
assertEquals(0x2033, snapshot.get("input.button.hold@1"));
}
@Test
void registryDefinitionsMustStayInSyncWithVmArchCsv() throws IOException {
final var specPath = locateRepoRoot().resolve(VM_ARCH_INTRINSICS_PATH);
assertTrue(Files.isRegularFile(specPath), "intrinsics spec is missing: " + specPath);
final var expected = parseVmArchIntrinsicRows(specPath);
final var actual = Arrays.stream(IRVMIntrinsicDefinition.values())
.map(IntrinsicCsvRow::fromDefinition)
.toList();
assertEquals(expected, actual);
}
@Test
void registryMustStayInSyncWithRuntimeBuiltinsTable() throws IOException {
final var compilerSnapshot = IRVMIntrinsicRegistry.snapshotByCanonicalIdentity();
if (!Files.exists(RUNTIME_INTRINSICS_FILE)) {
final var runtimeIntrinsicsFile = locateRuntimeIntrinsicsFile();
if (!Files.exists(runtimeIntrinsicsFile)) {
if (strictParityEnabled()) {
fail("runtime intrinsic table not found: " + RUNTIME_INTRINSICS_FILE.toAbsolutePath());
fail("runtime intrinsic table not found: " + runtimeIntrinsicsFile.toAbsolutePath());
}
return;
}
final var runtimeSnapshot = parseRuntimeIntrinsicSnapshot(RUNTIME_INTRINSICS_FILE);
final var runtimeSnapshot = parseRuntimeIntrinsicSnapshot(runtimeIntrinsicsFile);
assertEquals(runtimeSnapshot, compilerSnapshot, parityDiff(runtimeSnapshot, compilerSnapshot));
}
private List<IntrinsicCsvRow> parseVmArchIntrinsicRows(final Path specPath) throws IOException {
final var lines = Files.readAllLines(specPath, StandardCharsets.UTF_8);
final var rows = new ArrayList<IntrinsicCsvRow>();
for (int index = 0; index < lines.size(); index++) {
final var rawLine = lines.get(index);
final var line = rawLine.trim();
if (line.isBlank()) {
continue;
}
if (index == 0) {
assertEquals(
"final_id_hex,final_id_dec,canonical_name,canonical_version,owner,name,arg_slots,ret_slots,arg_layout,ret_layout,deterministic,may_allocate",
line,
"unexpected intrinsic csv header");
continue;
}
final var columns = line.split(",", -1);
if (columns.length != 12) {
fail("invalid intrinsics csv row at line " + (index + 1) + ": " + rawLine);
}
rows.add(new IntrinsicCsvRow(
normalizeHexId(columns[0]),
parseUnsignedInt(columns[1], "final_id_dec", index + 1),
requireNonBlank(columns[2], "canonical_name", index + 1),
parseLong(columns[3], "canonical_version", index + 1),
requireNonBlank(columns[4], "owner", index + 1),
requireNonBlank(columns[5], "name", index + 1),
parseInt(columns[6], "arg_slots", index + 1),
parseInt(columns[7], "ret_slots", index + 1),
columns[8].trim(),
columns[9].trim(),
parseBoolean(columns[10], "deterministic", index + 1),
parseBoolean(columns[11], "may_allocate", index + 1)));
}
return List.copyOf(rows);
}
private Map<String, Integer> parseRuntimeIntrinsicSnapshot(final Path runtimeFile) throws IOException {
final var runtimeSource = Files.readAllLines(runtimeFile, StandardCharsets.UTF_8);
final var mapped = new LinkedHashMap<String, Integer>();
@@ -109,6 +163,27 @@ class IRVMIntrinsicRegistryParityTest {
return Map.copyOf(mapped);
}
private Path locateRepoRoot() {
var cursor = Path.of(System.getProperty("user.dir")).toAbsolutePath().normalize();
while (cursor != null) {
if (Files.isDirectory(cursor.resolve("docs"))
&& Files.isDirectory(cursor.resolve("prometeu-compiler"))
&& Files.exists(cursor.resolve("settings.gradle.kts"))) {
return cursor;
}
cursor = cursor.getParent();
}
fail("could not locate repository root from working directory");
throw new IllegalStateException("unreachable");
}
private Path locateRuntimeIntrinsicsFile() {
return locateRepoRoot()
.getParent()
.resolve("runtime")
.resolve(RUNTIME_INTRINSICS_PATH);
}
private int parseRuntimeId(final String rawId) {
if (rawId.startsWith("0x") || rawId.startsWith("0X")) {
return Integer.parseUnsignedInt(rawId.substring(2), 16);
@@ -116,6 +191,73 @@ class IRVMIntrinsicRegistryParityTest {
return Integer.parseUnsignedInt(rawId, 10);
}
private String requireNonBlank(
final String value,
final String fieldName,
final int lineNumber) {
final var normalized = value.trim();
if (normalized.isBlank()) {
fail("blank " + fieldName + " at line " + lineNumber);
}
return normalized;
}
private int parseInt(
final String rawValue,
final String fieldName,
final int lineNumber) {
try {
return Integer.parseInt(rawValue.trim());
} catch (NumberFormatException ex) {
fail("invalid " + fieldName + " at line " + lineNumber + ": " + rawValue);
throw new IllegalStateException("unreachable", ex);
}
}
private long parseLong(
final String rawValue,
final String fieldName,
final int lineNumber) {
try {
return Long.parseLong(rawValue.trim());
} catch (NumberFormatException ex) {
fail("invalid " + fieldName + " at line " + lineNumber + ": " + rawValue);
throw new IllegalStateException("unreachable", ex);
}
}
private int parseUnsignedInt(
final String rawValue,
final String fieldName,
final int lineNumber) {
try {
return Integer.parseUnsignedInt(rawValue.trim(), 10);
} catch (NumberFormatException ex) {
fail("invalid " + fieldName + " at line " + lineNumber + ": " + rawValue);
throw new IllegalStateException("unreachable", ex);
}
}
private boolean parseBoolean(
final String rawValue,
final String fieldName,
final int lineNumber) {
return switch (rawValue.trim().toLowerCase(Locale.ROOT)) {
case "true" -> true;
case "false" -> false;
default -> {
fail("invalid " + fieldName + " at line " + lineNumber + ": " + rawValue);
yield false;
}
};
}
private String normalizeHexId(final String rawValue) {
final var trimmed = rawValue.trim();
final var parsed = parseRuntimeId(trimmed);
return "0x" + Integer.toUnsignedString(parsed, 16).toUpperCase(Locale.ROOT);
}
private boolean strictParityEnabled() {
final var strict = System.getenv(STRICT_PARITY_ENV);
if (isTruthy(strict)) {
@@ -160,4 +302,35 @@ class IRVMIntrinsicRegistryParityTest {
+ "\nmissingInRuntime=" + List.copyOf(missingInRuntime)
+ "\nidMismatches=" + List.copyOf(mismatchedIds);
}
private record IntrinsicCsvRow(
String finalIdHex,
int finalIdDec,
String canonicalName,
long canonicalVersion,
String owner,
String name,
int argSlots,
int retSlots,
String argLayout,
String retLayout,
boolean deterministic,
boolean mayAllocate) {
private static IntrinsicCsvRow fromDefinition(final IRVMIntrinsicDefinition definition) {
return new IntrinsicCsvRow(
"0x" + Integer.toUnsignedString(definition.finalId(), 16).toUpperCase(Locale.ROOT),
definition.finalId(),
definition.canonicalName(),
definition.canonicalVersion(),
definition.owner(),
definition.intrinsicName(),
definition.argSlots(),
definition.retSlots(),
definition.argLayout(),
definition.retLayout(),
definition.deterministic(),
definition.mayAllocate());
}
}
}