segment

Explore

Loading ....

View source

YAML

ethdebug/format/pointer/scheme/segment

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "schema:ethdebug/format/pointer/scheme/segment"

title: ethdebug/format/pointer/scheme/segment
description: |
  An addressing scheme for pointing to a range of bytes in a data location
  arranged as individually-addressable word-sized slots.

  **Note** that this addressing scheme permits addressing byte ranges that
  extend beyond the last byte of a particular slot, or even covering the range
  of multiple slots.

  In such cases, this schema defines the range as the concatenation of bytes
  across slots such that the address of the first byte after the end of slot
  `p` (i.e., `{ "offset": "$wordsize" }`) is interpreted as the first byte of
  slot `p + 1`.

type: object

properties:
  slot:
    $ref: "schema:ethdebug/format/pointer/expression"
  offset:
    description: |
      The starting byte index within the slot.

      Bytes within a slot are numbered from the most significant byte. A
      slot's value is its `$wordsize`-byte big-endian word, and byte `0` is
      the first byte of that word, as if the word were written to memory. An
      `offset` of `0` therefore addresses the most significant byte of the
      slot, and an `offset` of `$wordsize - 1` addresses the least
      significant byte.

      This field is **optional**. If unspecified, it has the default value of
      `0`, indicating that the segment begins at the start of the specified
      slot (its most significant byte).

      A data layout that counts bytes from the low-order end of a slot must
      convert: a value of `n` bytes that sits `o` bytes from the low-order end
      is at `offset` `$wordsize - o - n`. An emitter may write that number as
      a literal, which is the simplest form to read and resolve. It may also
      write the conversion as an expression, such as

      ```json
      {
        "$difference": ["$wordsize", { "$sum": [o, { ".length": "$this" }] }]
      }
      ```

      which can take `n` from the region's own `length`, keeps the layout's
      own numbers visible, needs no arithmetic in the emitter, and does not
      depend on a fixed word size.

      This field's expression must resolve to a non-negative value. It is
      **not** bounded by the word size: an offset that meets or exceeds
      `$wordsize` carries into subsequent slots. Given a `slot` value `p`
      and an `offset` value `n`, the segment begins at byte
      `n mod $wordsize` of slot `p + floor(n / $wordsize)`. (Equivalently,
      byte `{ "offset": "$wordsize" }` of slot `p` is byte `0` of slot
      `p + 1`, consistent with the multi-slot note above.) Emitters may
      therefore chain byte sums across a slot boundary without decomposing
      into slot and byte components themselves; a resolver recovers the
      effective slot and byte by division and remainder against
      `$wordsize`.
    $ref: "schema:ethdebug/format/pointer/expression"
    default: 0
  length:
    description: |
      The length of the bytes range this segment represents.

      This field is **optional**. If unspecified, its default value indicates
      that the segment ends at the end of the slot in which it begins (after
      applying any `offset` carry).

      If this field has value larger than the default value, i.e., if the
      segment extends beyond the last byte in the slot, then this segment is
      defined to be the concatenation of the sequentially-addressed slot(s)
      following the slot specified.
    $ref: "schema:ethdebug/format/pointer/expression"
    default:
      $difference:
        - $wordsize
        - $remainder:
            - .offset: $this
            - $wordsize

required:
  - slot

examples:
  - slot: 0
  - slot: 1
    length:
      $product:
        - $wordsize
        - 3
  # a carry example: an offset at or beyond `$wordsize` addresses a later
  # slot. Here `offset: $wordsize` is byte 0 of slot 1, so this segment is
  # the 4 bytes beginning there.
  - slot: 0
    offset: $wordsize
    length: 4
  # packed values: an `address` (20 bytes) at the low-order end of slot 2,
  # and a `uint32` (4 bytes) just above it, written with literal offsets
  - slot: 2
    offset: 12
    length: 20
  - slot: 2
    offset: 8
    length: 4
  # the same two values with the conversion `$wordsize - (o + n)` written as
  # an expression that takes `n` from the region's own length
  - slot: 2
    offset:
      $difference:
        - $wordsize
        - .length: $this
    length: 20
  - slot: 2
    offset:
      $difference:
        - $wordsize
        - $sum:
            - 20
            - .length: $this
    length: 4

JSON

ethdebug/format/pointer/scheme/segment

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "schema:ethdebug/format/pointer/scheme/segment",
  "title": "ethdebug/format/pointer/scheme/segment",
  "description": "An addressing scheme for pointing to a range of bytes in a data location\narranged as individually-addressable word-sized slots.\n\n**Note** that this addressing scheme permits addressing byte ranges that\nextend beyond the last byte of a particular slot, or even covering the range\nof multiple slots.\n\nIn such cases, this schema defines the range as the concatenation of bytes\nacross slots such that the address of the first byte after the end of slot\n`p` (i.e., `{ \"offset\": \"$wordsize\" }`) is interpreted as the first byte of\nslot `p + 1`.\n",
  "type": "object",
  "properties": {
    "slot": {
      "$ref": "schema:ethdebug/format/pointer/expression"
    },
    "offset": {
      "description": "The starting byte index within the slot.\n\nBytes within a slot are numbered from the most significant byte. A\nslot's value is its `$wordsize`-byte big-endian word, and byte `0` is\nthe first byte of that word, as if the word were written to memory. An\n`offset` of `0` therefore addresses the most significant byte of the\nslot, and an `offset` of `$wordsize - 1` addresses the least\nsignificant byte.\n\nThis field is **optional**. If unspecified, it has the default value of\n`0`, indicating that the segment begins at the start of the specified\nslot (its most significant byte).\n\nA data layout that counts bytes from the low-order end of a slot must\nconvert: a value of `n` bytes that sits `o` bytes from the low-order end\nis at `offset` `$wordsize - o - n`. An emitter may write that number as\na literal, which is the simplest form to read and resolve. It may also\nwrite the conversion as an expression, such as\n\n```json\n{\n  \"$difference\": [\"$wordsize\", { \"$sum\": [o, { \".length\": \"$this\" }] }]\n}\n```\n\nwhich can take `n` from the region's own `length`, keeps the layout's\nown numbers visible, needs no arithmetic in the emitter, and does not\ndepend on a fixed word size.\n\nThis field's expression must resolve to a non-negative value. It is\n**not** bounded by the word size: an offset that meets or exceeds\n`$wordsize` carries into subsequent slots. Given a `slot` value `p`\nand an `offset` value `n`, the segment begins at byte\n`n mod $wordsize` of slot `p + floor(n / $wordsize)`. (Equivalently,\nbyte `{ \"offset\": \"$wordsize\" }` of slot `p` is byte `0` of slot\n`p + 1`, consistent with the multi-slot note above.) Emitters may\ntherefore chain byte sums across a slot boundary without decomposing\ninto slot and byte components themselves; a resolver recovers the\neffective slot and byte by division and remainder against\n`$wordsize`.\n",
      "$ref": "schema:ethdebug/format/pointer/expression",
      "default": 0
    },
    "length": {
      "description": "The length of the bytes range this segment represents.\n\nThis field is **optional**. If unspecified, its default value indicates\nthat the segment ends at the end of the slot in which it begins (after\napplying any `offset` carry).\n\nIf this field has value larger than the default value, i.e., if the\nsegment extends beyond the last byte in the slot, then this segment is\ndefined to be the concatenation of the sequentially-addressed slot(s)\nfollowing the slot specified.\n",
      "$ref": "schema:ethdebug/format/pointer/expression",
      "default": {
        "$difference": [
          "$wordsize",
          {
            "$remainder": [
              {
                ".offset": "$this"
              },
              "$wordsize"
            ]
          }
        ]
      }
    }
  },
  "required": [
    "slot"
  ],
  "examples": [
    {
      "slot": 0
    },
    {
      "slot": 1,
      "length": {
        "$product": [
          "$wordsize",
          3
        ]
      }
    },
    {
      "slot": 0,
      "offset": "$wordsize",
      "length": 4
    },
    {
      "slot": 2,
      "offset": 12,
      "length": 20
    },
    {
      "slot": 2,
      "offset": 8,
      "length": 4
    },
    {
      "slot": 2,
      "offset": {
        "$difference": [
          "$wordsize",
          {
            ".length": "$this"
          }
        ]
      },
      "length": 20
    },
    {
      "slot": 2,
      "offset": {
        "$difference": [
          "$wordsize",
          {
            "$sum": [
              20,
              {
                ".length": "$this"
              }
            ]
          }
        ]
      },
      "length": 4
    }
  ]
}

Playground

Loading playground...