- {detailedAdmonition}
-
- See full ethdebug/format/program/instruction object
-
-
- >
- : <>
-
Details
- {basicAdmonition}
- >;
-
-
return <>
Interactive example
@@ -67,6 +23,6 @@ export function Viewer(props: Props): JSX.Element {
- {details}
+
>;
}
diff --git a/schemas/program/context.schema.yaml b/schemas/program/context.schema.yaml
index 18a67db4..5739ff40 100644
--- a/schemas/program/context.schema.yaml
+++ b/schemas/program/context.schema.yaml
@@ -7,17 +7,21 @@ description: |
information about the high-level runtime execution state at a specific point
in a program's bytecode.
- This schema defines the structure for encoding compile-time knowledge about
- the high-level runtime state. Contexts are treated as units of information
- that may encompass multiple related or unrelated facts about the program's
- state. This may include, e.g., source mapping information (via the `"code"`
- property) or information about known variable allocations, etc.
-
- The interpretation of a context depends on its properties and its
- relationship to program elements such as instructions or control flow
- structures. For example, a context associated with an instruction may
- indicate that the specified conditions hold true following the execution of
- that instruction.
+ This schema provides a formal specification for this format's model of what
+ information can be known at compile-time about the high-level runtime. This
+ includes data such as a particular machine instruction's source mapping or
+ what variables exist in runtime state following some instruction.
+
+ The context object supports dynamic context combination and selection through
+ the use of `gather`, and `pick` properties. This allows for flexible
+ composition and extraction of context information.
+
+ Contexts serve as a bridge between low-level EVM execution and high-level
+ language constructs. Debuggers can use these compile-time guarantees to
+ maintain a coherent view of the high-level language runtime throughout
+ program execution. This enables debugging tools to map execution points to
+ source code, reconstruct variable states, provide meaningful stack traces,
+ and offer insights into control flow and data structures.
type: object
@@ -34,6 +38,18 @@ allOf:
required: ["remark"]
then:
$ref: "schema:ethdebug/format/program/context/remark"
+ - if:
+ required: ["pick"]
+ then:
+ $ref: "schema:ethdebug/format/program/context/pick"
+ - if:
+ required: ["gather"]
+ then:
+ $ref: "schema:ethdebug/format/program/context/gather"
+ - if:
+ required: ["frame"]
+ then:
+ $ref: "schema:ethdebug/format/program/context/frame"
unevaluatedProperties: false
diff --git a/schemas/program/context/frame.schema.yaml b/schemas/program/context/frame.schema.yaml
new file mode 100644
index 00000000..797c8c06
--- /dev/null
+++ b/schemas/program/context/frame.schema.yaml
@@ -0,0 +1,20 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/program/context/frame"
+
+title: ethdebug/format/program/context/frame
+description: |
+ A context may specify a `"frame"` property to indicate that its facts apply
+ only to one of several possible compilation frames, e.g. for compilers with
+ distinct frontend/backends to specify debugging data for the IR separately
+ from the debugging data for the source language.
+type: object
+properties:
+ frame:
+ title: Relevant compilation frame
+ type: string
+required:
+ - frame
+
+examples:
+ - frame: "ir"
+ - frame: "source"
diff --git a/schemas/program/context/gather.schema.yaml b/schemas/program/context/gather.schema.yaml
new file mode 100644
index 00000000..59c5768b
--- /dev/null
+++ b/schemas/program/context/gather.schema.yaml
@@ -0,0 +1,58 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/program/context/gather"
+
+title: ethdebug/format/program/context/gather
+description: |
+ A context specifying the `"gather"` property with a list of contexts
+ indicates that all specified contexts apply simultaneously.
+
+type: object
+properties:
+ gather:
+ title: Contexts to gather
+ type: array
+ items:
+ $ref: "schema:ethdebug/format/program/context"
+ minItems: 2
+ additionalItems: false
+required:
+ - gather
+
+examples:
+ - gather:
+ - frame: "ir"
+ code:
+ source:
+ id: 0
+ range:
+ offset: 8
+ length: 11
+ - frame: "source"
+ code:
+ source:
+ id: 3
+ range:
+ offset: 113
+ length: 19
+ - gather:
+ - variables:
+ - identifier: x
+ declaration:
+ source:
+ id: 5
+ range:
+ offset: 10
+ length: 56
+ type:
+ kind: string
+ - variables:
+ - identifier: x
+ declaration:
+ source:
+ id: 5
+ range:
+ offset: 10
+ length: 56
+ pointer:
+ location: storage
+ slot: 0
diff --git a/schemas/program/context/pick.schema.yaml b/schemas/program/context/pick.schema.yaml
new file mode 100644
index 00000000..18cf04dd
--- /dev/null
+++ b/schemas/program/context/pick.schema.yaml
@@ -0,0 +1,35 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/program/context/pick"
+
+title: ethdebug/format/program/context/pick
+description: |
+ A program context that specifies the `"pick"` property indicates that
+ one of several possible contexts are known to be true, possibly requiring
+ additional information to disambiguate.
+
+type: object
+properties:
+ pick:
+ title: Contexts to pick from
+ type: array
+ items:
+ $ref: "schema:ethdebug/format/program/context"
+ minItems: 2
+ additionalItems: false
+required:
+ - pick
+
+examples:
+ - pick:
+ - code:
+ source:
+ id: 5
+ range:
+ offset: 68
+ length: 16
+ - code:
+ source:
+ id: 5
+ range:
+ offset: 132
+ length: 16