Instruction schema

Explore

Loading ....

View source

YAML

ethdebug/format/program/instruction

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "schema:ethdebug/format/program/instruction"

title: ethdebug/format/program/instruction
description: |
  A schema for representing the information pertaining to a particular
  instruction in machine code.

type: object

properties:
  offset:
    title: Instruction byte offset
    description: |
      The byte offset where the instruction begins within the bytecode.

      For legacy contract bytecode (non-EOF), this value is equivalent to the
      instruction's program counter. For EOF bytecode, this value **must** be
      the offset from the start of the container, not the start of a particular
      code section within that container.
    $ref: "schema:ethdebug/format/data/value"

  operation:
    title: Machine operation information
    type: object
    properties:
      mnemonic:
        description: The mnemonic operation code (PUSH1, e.g.)
        type: string

      arguments:
        description: The immediate arguments to the operation, if relevant.
        type: array
        minItems: 1
        items:
          description: |
            An immediate value specified as argument to the opcode
          $ref: "schema:ethdebug/format/data/value"

    required:
      - mnemonic

  context:
    description: |
      The context that holds **following** the execution of this
      instruction. Both its semantic facts (source location, variables in
      scope, function invocation, etc.) and any pointers it contains resolve
      against the machine state **after** the instruction has executed
      (its postcondition).

      Instruction contexts form a chain. The program-level `context` is the
      base case: the precondition that holds before the first instruction
      executes. Each instruction's context is then the postcondition of that
      instruction, which is in turn the precondition of the next. A debugger
      paused at the trace step about to execute instruction *i* therefore
      reads the context of instruction *i − 1* — or, before the first
      instruction, the program-level `context`. Equivalently, prepending
      the program-level `context` to the sequence of instruction contexts
      yields a single sequence indexed by trace position, with no special
      case: the context in effect when about to execute the instruction at
      position *i* is element *i* of that sequence.

      This field is **optional**. Omitting it is equivalent to specifying the
      empty context value (`{}`).
    $ref: "schema:ethdebug/format/program/context"
    default: {}

required:
  - offset

unevaluatedProperties: false

examples:
  - offset: 0
    operation:
      mnemonic: "PUSH1"
      arguments: ["0x60"]
    context:
      code:
        source:
          id: "5"
        range:
          offset: 10
          length: 30

JSON

ethdebug/format/program/instruction

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "schema:ethdebug/format/program/instruction",
  "title": "ethdebug/format/program/instruction",
  "description": "A schema for representing the information pertaining to a particular\ninstruction in machine code.\n",
  "type": "object",
  "properties": {
    "offset": {
      "title": "Instruction byte offset",
      "description": "The byte offset where the instruction begins within the bytecode.\n\nFor legacy contract bytecode (non-EOF), this value is equivalent to the\ninstruction's program counter. For EOF bytecode, this value **must** be\nthe offset from the start of the container, not the start of a particular\ncode section within that container.\n",
      "$ref": "schema:ethdebug/format/data/value"
    },
    "operation": {
      "title": "Machine operation information",
      "type": "object",
      "properties": {
        "mnemonic": {
          "description": "The mnemonic operation code (PUSH1, e.g.)",
          "type": "string"
        },
        "arguments": {
          "description": "The immediate arguments to the operation, if relevant.",
          "type": "array",
          "minItems": 1,
          "items": {
            "description": "An immediate value specified as argument to the opcode\n",
            "$ref": "schema:ethdebug/format/data/value"
          }
        }
      },
      "required": [
        "mnemonic"
      ]
    },
    "context": {
      "description": "The context that holds **following** the execution of this\ninstruction. Both its semantic facts (source location, variables in\nscope, function invocation, etc.) and any pointers it contains resolve\nagainst the machine state **after** the instruction has executed\n(its postcondition).\n\nInstruction contexts form a chain. The program-level `context` is the\nbase case: the precondition that holds before the first instruction\nexecutes. Each instruction's context is then the postcondition of that\ninstruction, which is in turn the precondition of the next. A debugger\npaused at the trace step about to execute instruction *i* therefore\nreads the context of instruction *i − 1* — or, before the first\ninstruction, the program-level `context`. Equivalently, prepending\nthe program-level `context` to the sequence of instruction contexts\nyields a single sequence indexed by trace position, with no special\ncase: the context in effect when about to execute the instruction at\nposition *i* is element *i* of that sequence.\n\nThis field is **optional**. Omitting it is equivalent to specifying the\nempty context value (`{}`).\n",
      "$ref": "schema:ethdebug/format/program/context",
      "default": {}
    }
  },
  "required": [
    "offset"
  ],
  "unevaluatedProperties": false,
  "examples": [
    {
      "offset": 0,
      "operation": {
        "mnemonic": "PUSH1",
        "arguments": [
          "0x60"
        ]
      },
      "context": {
        "code": {
          "source": {
            "id": "5"
          },
          "range": {
            "offset": 10,
            "length": 30
          }
        }
      }
    }
  ]
}

Playground

Loading playground...