diff --git a/vadl/main/vadl/ast/Expr.java b/vadl/main/vadl/ast/Expr.java index 074af9e15..003ab223d 100644 --- a/vadl/main/vadl/ast/Expr.java +++ b/vadl/main/vadl/ast/Expr.java @@ -1,4 +1,4 @@ -// SPDX-FileCopyrightText : © 2025 TU Wien +// SPDX-FileCopyrightText : © 2025-2026 TU Wien // SPDX-License-Identifier: GPL-3.0-or-later // // This program is free software: you can redistribute it and/or modify @@ -152,6 +152,11 @@ interface ExprVisitor { R visit(ResourceReferenceExression expr); } +/** + * A reference to a named entity in the specification. + * The {@link #target} field is resolved during symbol resolving to point to the + * referenced {@link Node}. + */ final class Identifier extends Expr implements IsId, IdentifierOrPlaceholder { String name; SourceLocation loc; @@ -484,6 +489,11 @@ public int hashCode() { } } +/** + * A unary expression using prefix notation. + * Supported operators are {@code -} (negation), {@code !} (logical not), + * and {@code ~} (bitwise complement). + */ class UnaryExpr extends Expr { IsUnOp operator; @Child @@ -559,6 +569,11 @@ public int hashCode() { } } +/** + * A positive integer literal in decimal form. + * Digits can be separated with {@code '} for readability (e.g. {@code 1'000'000}). + * Negative numeric literals are represented by applying the negation {@link UnaryExpr}. + */ class IntegerLiteral extends Expr { String token; BigInteger number; @@ -620,6 +635,9 @@ public int hashCode() { } } +/** + * A wildcard literal ({@code *}) used as a catch-all pattern in match expressions. + */ class WildcardLiteral extends Expr { SourceLocation loc; @@ -720,6 +738,9 @@ public int hashCode() { } } +/** + * A boolean literal ({@code true} or {@code false}). + */ class BoolLiteral extends Expr { boolean value; SourceLocation loc; @@ -773,6 +794,10 @@ public int hashCode() { } } +/** + * A string literal delimited by double quotes. + * Like {@code "apfelstrudel"} + */ class StringLiteral extends Expr { String token; String value; @@ -1293,6 +1318,10 @@ public int hashCode() { } } +/** + * A range expression of the form {@code from..to}. + * Used in forall expression/statements, slicing, and sequence literals. + */ class RangeExpr extends Expr { @Child Expr from; @@ -1511,6 +1540,12 @@ default IsId path() { Node target(); } +/** + * An identifier path pointing to one or multiple nested namespaces, separated by {@code ::}. + * The first N-1 segments are namespace references and the last segment is the actual identifier. + * + *

Example: {@code MyIsa::MyFormat::fieldName} + */ final class IdentifierPath extends Expr implements IsId { /** * List of segments in this path; the first N-1 segments are (nested) namespaces, @@ -1993,6 +2028,11 @@ public SourceLocation location() { } } +/** + * A conditional expression of the form {@code if condition then thenExpr else elseExpr}. + * Unlike {@link IfStatement}, the expression form always requires an else branch + * since it must evaluate to a value. + */ class IfExpr extends Expr { @Child Expr condition; @@ -2066,6 +2106,12 @@ public int hashCode() { } } +/** + * A let expression that binds a value to one or more identifiers within a body expression. + * Written as {@code let x = expr in body}. + * Supports tuple unpacking when multiple identifiers are provided: + * {@code let a, b = tupleExpr in body}. + */ class LetExpr extends Expr { List identifiers; @Child @@ -2170,6 +2216,12 @@ public int hashCode() { } } +/** + * A type cast expression using the {@code as} keyword. + * Performs explicit type conversions between VADL types, e.g. for signed/unsigned arithmetic. + * + *

Example: {@code value as UInt<32>} + */ class CastExpr extends Expr { @Child Expr value; @@ -2241,6 +2293,12 @@ public int hashCode() { } } +/** + * A match expression that selects a result based on pattern matching. + * Written as {@code match expr with { pattern => result, ..., _ => default }}. + * Each case has one or more patterns on the LHS and a result expression on the RHS of {@code =>}. + * Must contain a wildcard {@code _} as the default catch-all case. + */ class MatchExpr extends Expr { Expr candidate; List cases; @@ -2369,6 +2427,11 @@ public int hashCode() { } } +/** + * An existential quantifier expression over a set of operations. + * Written as {@code exists in {op1, op2, ...}}. + * Evaluates to true if the current context matches any of the listed operations. + */ class ExistsInExpr extends Expr { List operations; SourceLocation loc; @@ -2425,6 +2488,11 @@ public int hashCode() { } } +/** + * An existential quantifier expression with a body. + * Written as {@code exists x in {op1, op2, ...} then expr}. + * Binds identifiers to operations from the given set and evaluates the body expression. + */ class ExistsInThenExpr extends Expr { List conditions; @Child @@ -2625,6 +2693,12 @@ enum Operation { } } +/** + * A reference literal that references a structural element using the {@code @} prefix. + * Written as {@code @identifier}, e.g. {@code @PC} to reference the program counter resource. + * This syntax is mostly used in the microarchitecture to differentiate between direct usages and + * references. + */ class ResourceReferenceExression extends Expr { @Child Identifier resource; @@ -2672,6 +2746,12 @@ public int hashCode() { } } +/** + * A sequence call expression used in the ABI modeling view to represent a list of alias + * registers with the same identifier. + * Provides syntactic sugar like {@code a{1..4}} which is equivalent to listing + * {@code a1, a2, a3, a4} individually. + */ class SequenceCallExpr extends Expr { @Child diff --git a/vadl/main/vadl/ast/Statement.java b/vadl/main/vadl/ast/Statement.java index 7b7e1d909..32ace8c62 100644 --- a/vadl/main/vadl/ast/Statement.java +++ b/vadl/main/vadl/ast/Statement.java @@ -1,4 +1,4 @@ -// SPDX-FileCopyrightText : © 2025 TU Wien +// SPDX-FileCopyrightText : © 2025-2026 TU Wien // SPDX-License-Identifier: GPL-3.0-or-later // // This program is free software: you can redistribute it and/or modify @@ -66,6 +66,9 @@ interface StatementVisitor { T visit(StatementList statement); } +/** + * A block of multiple statements surrounded by curly braces. + */ final class BlockStatement extends Statement { @Child List statements; @@ -216,6 +219,11 @@ R accept(StatementVisitor visitor) { } } +/** + * A conditional statement of the form {@code if condition then thenStmt else elseStmt}. + * Unlike {@link IfExpr}, the else branch is optional since a statement does not need + * to produce a value. + */ final class IfStatement extends Statement { @Child Expr condition; @@ -280,6 +288,10 @@ R accept(StatementVisitor visitor) { } } +/** + * An assignment statement that stores a value in a register, register file, or memory location. + * The target (LHS) and value expression (RHS) are separated by the {@code :=} operator. + */ final class AssignmentStatement extends Statement { @Child Expr target; @@ -333,6 +345,9 @@ R accept(StatementVisitor visitor) { } } +/** + * An ordered list of statements executed sequentially. + */ final class StatementList extends Statement { @Child @@ -365,6 +380,12 @@ R accept(StatementVisitor visitor) { } } +/** + * Marks the following statement as exceptional code. + * After the raise statement finishes, no further instruction behavior is executed. + * + * @see ExceptionDefinition + */ final class RaiseStatement extends Statement { @Child @@ -413,6 +434,10 @@ R accept(StatementVisitor visitor) { } } +/** + * A standalone call statement (e.g. a function or instruction call without assignment). + * Used for pseudo instruction definitions and ABI sequence definitions. + */ final class CallStatement extends Statement { @Child @@ -456,6 +481,10 @@ R accept(StatementVisitor visitor) { } } +/** + * An internal temporary placeholder node inside model definitions. + * This node should never leave the parser. + */ final class PlaceholderStatement extends Statement { List segments; @@ -598,6 +627,12 @@ R accept(StatementVisitor visitor) { } } +/** + * A match statement that selects a statement to execute based on pattern matching. + * Written as {@code match expr with { pattern => stmt, ..., _ => default }}. + * Each case has one or more patterns on the LHS and a statement on the RHS of {@code =>}. + * The wildcard {@code _} default case is optional for statements (unlike {@link MatchExpr}). + */ final class MatchStatement extends Statement { Expr candidate; List cases; @@ -741,6 +776,11 @@ R accept(StatementVisitor visitor) { } } +/** + * A call to an instruction or pseudo instruction. + * Supports both named arguments (using mapping syntax {@code {name = value}}) + * and unnamed positional arguments. + */ final class InstructionCallStatement extends Statement { @Child @@ -885,6 +925,13 @@ public String toString() { } } +/** + * A lock statement that gains exclusive access to a memory part, + * guaranteeing atomic read-modify-write operations. + * The lock is automatically released after the subsequent statement or block completes. + * + *

Written as {@code lock expr in statement}. + */ final class LockStatement extends Statement { @Child Expr expr; @@ -1006,6 +1053,11 @@ R accept(StatementVisitor visitor) { } +/** + * An index variable binding in a {@link ForallStatement} or {@link ForallExpr}. + * Binds a name to a range domain. + * e.g. {@code i: Bits<8> in 0..3}. + */ final class ForallIndex extends Node implements IdentifiableNode { @Child IsId name;