@typeberry/lib 0.5.1-a4d7c93 → 0.5.1-eb84786

package/packages/core/pvm-interpreter/memory/memory-builder.js

@@ -0,0 +1,123 @@
+import { check } from "#@typeberry/utils";
+import { FinalizedBuilderModification, IncorrectSbrkIndex, PageNotExist, ReservedMemoryFault } from "./errors.js";
+import { Memory } from "./memory.js";
+import { PAGE_SIZE } from "./memory-consts.js";
+import { tryAsSbrkIndex } from "./memory-index.js";
+import { MemoryRange, RESERVED_MEMORY_RANGE } from "./memory-range.js";
+import { getPageNumber } from "./memory-utils.js";
+import { PageRange } from "./page-range.js";
+import { ReadablePage, WriteablePage } from "./pages/index.js";
+import { tryAsPageIndex } from "./pages/page-utils.js";
+export class MemoryBuilder {
+    initialMemory = new Map();
+    isFinalized = false;
+    ensureNotFinalized() {
+        if (this.isFinalized) {
+            throw new FinalizedBuilderModification();
+        }
+    }
+    ensureNoReservedMemoryUsage(range) {
+        if (range.overlapsWith(RESERVED_MEMORY_RANGE)) {
+            throw new ReservedMemoryFault();
+        }
+    }
+    /**
+     * Create entire readable pages to handle the `[start, end)` range.
+     *
+     * Note that both `start` and `end` must be multiple of the `PAGE_SIZE`, i.e.
+     * they need to be the start indices of the pages.
+     *
+     * The data passed will be placed at `start`, but might be shorter than the requested range,
+     * prepend it with zeros if you don't wish to have it at the beginning of the page.
+     */
+    setReadablePages(start, end, data = new Uint8Array()) {
+        this.ensureNotFinalized();
+        check `${start < end} end has to be bigger than start`;
+        check `${start % PAGE_SIZE === 0} start needs to be a multiple of page size (${PAGE_SIZE})`;
+        check `${end % PAGE_SIZE === 0} end needs to be a multiple of page size (${PAGE_SIZE})`;
+        check `${data.length <= end - start} the initial data is longer than address range`;
+        const length = end - start;
+        const range = MemoryRange.fromStartAndLength(start, length);
+        this.ensureNoReservedMemoryUsage(range);
+        const pages = Array.from(PageRange.fromMemoryRange(range));
+        const noOfPages = pages.length;
+        for (let i = 0; i < noOfPages; i++) {
+            const pageNumber = pages[i];
+            const dataChunk = data.subarray(i * PAGE_SIZE, (i + 1) * PAGE_SIZE);
+            const page = new ReadablePage(pageNumber, dataChunk);
+            this.initialMemory.set(pageNumber, page);
+        }
+        return this;
+    }
+    /**
+     * Create entire writeable pages to handle the `[start, end)` range.
+     *
+     * Note that both `start` and `end` must be multiple of the `PAGE_SIZE`, i.e.
+     * they need to be the start indices of the pages.
+     *
+     * The data passed will be placed at `start`, but might be shorter than the requested range,
+     * prepend it with zeros if you don't wish to have it at the beginning of the page.
+     */
+    setWriteablePages(start, end, data = new Uint8Array()) {
+        this.ensureNotFinalized();
+        check `${start < end} end has to be bigger than start`;
+        check `${start % PAGE_SIZE === 0} start needs to be a multiple of page size (${PAGE_SIZE})`;
+        check `${end % PAGE_SIZE === 0} end needs to be a multiple of page size (${PAGE_SIZE})`;
+        check `${data.length <= end - start} the initial data is longer than address range`;
+        const length = end - start;
+        const range = MemoryRange.fromStartAndLength(start, length);
+        this.ensureNoReservedMemoryUsage(range);
+        const pages = Array.from(PageRange.fromMemoryRange(range));
+        const noOfPages = pages.length;
+        for (let i = 0; i < noOfPages; i++) {
+            const pageNumber = pages[i];
+            const dataChunk = data.subarray(i * PAGE_SIZE, (i + 1) * PAGE_SIZE);
+            const page = new WriteablePage(pageNumber, dataChunk);
+            this.initialMemory.set(pageNumber, page);
+        }
+        return this;
+    }
+    /**
+     * This function can be useful when page map and initial memory data are provided separatelly.
+     * You can use setWriteablePages/setReadablePages to create empty pages and then setData to fill them
+     */
+    setData(start, data) {
+        this.ensureNotFinalized();
+        const pageOffset = start % PAGE_SIZE;
+        const remainingSpaceOnPage = PAGE_SIZE - pageOffset;
+        check `${data.length <= remainingSpaceOnPage} The data has to fit into a single page.`;
+        const length = data.length;
+        const range = MemoryRange.fromStartAndLength(start, length);
+        this.ensureNoReservedMemoryUsage(range);
+        const pageNumber = getPageNumber(start);
+        const page = this.initialMemory.get(pageNumber);
+        if (page === undefined) {
+            throw new PageNotExist();
+        }
+        const startPageIndex = tryAsPageIndex(start - page.start);
+        page.setData(startPageIndex, data);
+        return this;
+    }
+    finalize(startHeapIndex, endHeapIndex) {
+        check `
+      ${startHeapIndex <= endHeapIndex}
+      startHeapIndex (${startHeapIndex}) has to be less than or equal to endHeapIndex (${endHeapIndex})
+    `;
+        this.ensureNotFinalized();
+        const heapRange = MemoryRange.fromStartAndLength(startHeapIndex, endHeapIndex - startHeapIndex);
+        const heapPagesRange = PageRange.fromMemoryRange(heapRange);
+        const initializedPageNumbers = Array.from(this.initialMemory.keys());
+        for (const pageNumber of initializedPageNumbers) {
+            if (heapPagesRange.isInRange(pageNumber)) {
+                throw new IncorrectSbrkIndex();
+            }
+        }
+        const memory = Memory.fromInitialMemory({
+            memory: this.initialMemory,
+            sbrkIndex: tryAsSbrkIndex(startHeapIndex),
+            endHeapIndex,
+        });
+        this.isFinalized = true;
+        return memory;
+    }
+}

package/packages/core/pvm-interpreter/memory/memory-builder.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=memory-builder.test.d.ts.map

package/packages/core/pvm-interpreter/memory/memory-builder.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-builder.test.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/pvm-interpreter/memory/memory-builder.test.ts"],"names":[],"mappings":""}

package/packages/core/pvm-interpreter/memory/memory-builder.test.js

@@ -0,0 +1,122 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { MEMORY_SIZE } from "#@typeberry/pvm-interface";
+import { IncorrectSbrkIndex } from "./errors.js";
+import { MemoryBuilder } from "./memory-builder.js";
+import { PAGE_SIZE, RESERVED_NUMBER_OF_PAGES } from "./memory-consts.js";
+import { tryAsMemoryIndex, tryAsSbrkIndex } from "./memory-index.js";
+import { ReadablePage, WriteablePage } from "./pages/index.js";
+import { tryAsPageNumber } from "./pages/page-utils.js";
+describe("MemoryBuilder", () => {
+    describe("finalize", () => {
+        it("should work correctly (happy path)", () => {
+            const builder = new MemoryBuilder();
+            const pageMap = new Map();
+            pageMap.set(RESERVED_NUMBER_OF_PAGES, new ReadablePage(tryAsPageNumber(RESERVED_NUMBER_OF_PAGES), new Uint8Array()));
+            pageMap.set(RESERVED_NUMBER_OF_PAGES + 1, new WriteablePage(tryAsPageNumber(RESERVED_NUMBER_OF_PAGES + 1), new Uint8Array()));
+            const expectedMemory = {
+                endHeapIndex: (RESERVED_NUMBER_OF_PAGES + 4) * PAGE_SIZE,
+                sbrkIndex: (RESERVED_NUMBER_OF_PAGES + 2) * PAGE_SIZE,
+                virtualSbrkIndex: (RESERVED_NUMBER_OF_PAGES + 2) * PAGE_SIZE,
+                memory: pageMap,
+            };
+            const memory = builder
+                .setReadablePages(tryAsMemoryIndex(RESERVED_NUMBER_OF_PAGES * PAGE_SIZE), tryAsMemoryIndex((RESERVED_NUMBER_OF_PAGES + 1) * PAGE_SIZE), new Uint8Array())
+                .setWriteablePages(tryAsMemoryIndex((RESERVED_NUMBER_OF_PAGES + 1) * PAGE_SIZE), tryAsMemoryIndex((RESERVED_NUMBER_OF_PAGES + 2) * PAGE_SIZE), new Uint8Array())
+                .finalize(tryAsMemoryIndex((RESERVED_NUMBER_OF_PAGES + 2) * PAGE_SIZE), tryAsSbrkIndex((RESERVED_NUMBER_OF_PAGES + 4) * PAGE_SIZE));
+            assert.deepEqual(memory, expectedMemory);
+        });
+        it("should throw IncorrectSbrkIndex exception when some page are in heap segment", () => {
+            const builder = new MemoryBuilder();
+            const tryToBuildMemory = () => builder
+                .setReadablePages(tryAsMemoryIndex(RESERVED_NUMBER_OF_PAGES * PAGE_SIZE), tryAsMemoryIndex((RESERVED_NUMBER_OF_PAGES + 1) * PAGE_SIZE), new Uint8Array())
+                .setWriteablePages(tryAsMemoryIndex((RESERVED_NUMBER_OF_PAGES + 1) * PAGE_SIZE), tryAsMemoryIndex((RESERVED_NUMBER_OF_PAGES + 2) * PAGE_SIZE), new Uint8Array())
+                .finalize(tryAsMemoryIndex(RESERVED_NUMBER_OF_PAGES * PAGE_SIZE), tryAsSbrkIndex((RESERVED_NUMBER_OF_PAGES + 4) * PAGE_SIZE));
+            assert.throws(tryToBuildMemory, new IncorrectSbrkIndex());
+        });
+        it("should correctly finalize empty memory with full range heap", () => {
+            const builder = new MemoryBuilder();
+            const pageMap = new Map();
+            const heapStart = RESERVED_NUMBER_OF_PAGES * PAGE_SIZE;
+            const heapEnd = MEMORY_SIZE;
+            const expectedMemory = {
+                endHeapIndex: heapEnd,
+                sbrkIndex: heapStart,
+                virtualSbrkIndex: heapStart,
+                memory: pageMap,
+            };
+            const memory = builder.finalize(tryAsMemoryIndex(heapStart), tryAsSbrkIndex(heapEnd));
+            assert.deepEqual(memory, expectedMemory);
+        });
+    });
+    describe("paged memory", () => {
+        it("should add readable page", () => {
+            const builder = new MemoryBuilder();
+            const pageMap = new Map();
+            pageMap.set(RESERVED_NUMBER_OF_PAGES, new ReadablePage(tryAsPageNumber(RESERVED_NUMBER_OF_PAGES), new Uint8Array()));
+            const expectedMemory = {
+                endHeapIndex: (RESERVED_NUMBER_OF_PAGES + 3) * PAGE_SIZE,
+                sbrkIndex: (RESERVED_NUMBER_OF_PAGES + 2) * PAGE_SIZE,
+                virtualSbrkIndex: (RESERVED_NUMBER_OF_PAGES + 2) * PAGE_SIZE,
+                memory: pageMap,
+            };
+            const memory = builder
+                .setReadablePages(tryAsMemoryIndex(RESERVED_NUMBER_OF_PAGES * PAGE_SIZE), tryAsMemoryIndex((RESERVED_NUMBER_OF_PAGES + 1) * PAGE_SIZE), new Uint8Array())
+                .finalize(tryAsMemoryIndex((RESERVED_NUMBER_OF_PAGES + 2) * PAGE_SIZE), tryAsSbrkIndex((RESERVED_NUMBER_OF_PAGES + 3) * PAGE_SIZE));
+            assert.deepEqual(memory, expectedMemory);
+        });
+        it("should add writeable page", () => {
+            const builder = new MemoryBuilder();
+            const pageMap = new Map();
+            pageMap.set(RESERVED_NUMBER_OF_PAGES + 2, new WriteablePage(tryAsPageNumber(RESERVED_NUMBER_OF_PAGES + 2), new Uint8Array()));
+            const expectedMemory = {
+                endHeapIndex: (RESERVED_NUMBER_OF_PAGES + 4) * PAGE_SIZE,
+                sbrkIndex: (RESERVED_NUMBER_OF_PAGES + 3) * PAGE_SIZE,
+                virtualSbrkIndex: (RESERVED_NUMBER_OF_PAGES + 3) * PAGE_SIZE,
+                memory: pageMap,
+            };
+            const memory = builder
+                .setWriteablePages(tryAsMemoryIndex((RESERVED_NUMBER_OF_PAGES + 2) * PAGE_SIZE), tryAsMemoryIndex((RESERVED_NUMBER_OF_PAGES + 3) * PAGE_SIZE), new Uint8Array())
+                .finalize(tryAsMemoryIndex((RESERVED_NUMBER_OF_PAGES + 3) * PAGE_SIZE), tryAsSbrkIndex((RESERVED_NUMBER_OF_PAGES + 4) * PAGE_SIZE));
+            assert.deepEqual(memory, expectedMemory);
+        });
+        it("should add two pages", () => {
+            const builder = new MemoryBuilder();
+            const pageMap = new Map();
+            pageMap.set(RESERVED_NUMBER_OF_PAGES, new ReadablePage(tryAsPageNumber(RESERVED_NUMBER_OF_PAGES), new Uint8Array()));
+            pageMap.set(RESERVED_NUMBER_OF_PAGES + 1, new WriteablePage(tryAsPageNumber(RESERVED_NUMBER_OF_PAGES + 1), new Uint8Array()));
+            const expectedMemory = {
+                endHeapIndex: (RESERVED_NUMBER_OF_PAGES + 4) * PAGE_SIZE,
+                sbrkIndex: (RESERVED_NUMBER_OF_PAGES + 2) * PAGE_SIZE,
+                virtualSbrkIndex: (RESERVED_NUMBER_OF_PAGES + 2) * PAGE_SIZE,
+                memory: pageMap,
+            };
+            const memory = builder
+                .setReadablePages(tryAsMemoryIndex(RESERVED_NUMBER_OF_PAGES * PAGE_SIZE), tryAsMemoryIndex((RESERVED_NUMBER_OF_PAGES + 1) * PAGE_SIZE), new Uint8Array())
+                .setWriteablePages(tryAsMemoryIndex((RESERVED_NUMBER_OF_PAGES + 1) * PAGE_SIZE), tryAsMemoryIndex((RESERVED_NUMBER_OF_PAGES + 2) * PAGE_SIZE), new Uint8Array())
+                .finalize(tryAsMemoryIndex((RESERVED_NUMBER_OF_PAGES + 2) * PAGE_SIZE), tryAsSbrkIndex((RESERVED_NUMBER_OF_PAGES + 4) * PAGE_SIZE));
+            assert.deepEqual(memory, expectedMemory);
+        });
+    });
+    describe("setData", () => {
+        it("should add writeable page and set data separately", () => {
+            const builder = new MemoryBuilder();
+            const pageMap = new Map();
+            const data = new Uint8Array(PAGE_SIZE).fill(1);
+            const pageNumber = tryAsPageNumber(RESERVED_NUMBER_OF_PAGES);
+            const address = tryAsMemoryIndex(pageNumber * PAGE_SIZE);
+            pageMap.set(pageNumber, new WriteablePage(pageNumber, data));
+            const expectedMemory = {
+                endHeapIndex: (RESERVED_NUMBER_OF_PAGES + 4) * PAGE_SIZE,
+                sbrkIndex: (RESERVED_NUMBER_OF_PAGES + 2) * PAGE_SIZE,
+                virtualSbrkIndex: (RESERVED_NUMBER_OF_PAGES + 2) * PAGE_SIZE,
+                memory: pageMap,
+            };
+            const memory = builder
+                .setWriteablePages(tryAsMemoryIndex(RESERVED_NUMBER_OF_PAGES * PAGE_SIZE), tryAsMemoryIndex((RESERVED_NUMBER_OF_PAGES + 1) * PAGE_SIZE))
+                .setData(address, data)
+                .finalize(tryAsMemoryIndex((RESERVED_NUMBER_OF_PAGES + 2) * PAGE_SIZE), tryAsSbrkIndex((RESERVED_NUMBER_OF_PAGES + 4) * PAGE_SIZE));
+            assert.deepEqual(memory, expectedMemory);
+        });
+    });
+});

package/packages/core/pvm-interpreter/memory/memory-consts.d.ts

@@ -0,0 +1,9 @@
+export declare const PAGE_SIZE_SHIFT = 12;
+export declare const PAGE_SIZE: number;
+export declare const MIN_ALLOCATION_LENGTH: number;
+export declare const LAST_PAGE_NUMBER: number;
+/** https://graypaper.fluffylabs.dev/#/68eaa1f/35a60235a602?v=0.6.4 */
+export declare const RESERVED_NUMBER_OF_PAGES = 16;
+/** https://graypaper.fluffylabs.dev/#/68eaa1f/35a60235a602?v=0.6.4 */
+export declare const MAX_NUMBER_OF_PAGES: number;
+//# sourceMappingURL=memory-consts.d.ts.map

package/packages/core/pvm-interpreter/memory/memory-consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-consts.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/pvm-interpreter/memory/memory-consts.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC,eAAO,MAAM,SAAS,QAAuB,CAAC;AAO9C,eAAO,MAAM,qBAAqB,QAAoC,CAAC;AACvE,eAAO,MAAM,gBAAgB,QAAwC,CAAC;AAEtE,sEAAsE;AACtE,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAC3C,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,QAA0B,CAAC"}

package/packages/core/pvm-interpreter/memory/memory-consts.js

@@ -0,0 +1,16 @@
+import { MEMORY_SIZE } from "#@typeberry/pvm-interface";
+import { check } from "#@typeberry/utils";
+export const PAGE_SIZE_SHIFT = 12;
+// PAGE_SIZE has to be a power of 2
+export const PAGE_SIZE = 1 << PAGE_SIZE_SHIFT;
+const MIN_ALLOCATION_SHIFT = (() => {
+    const MIN_ALLOCATION_SHIFT = 7;
+    check `${MIN_ALLOCATION_SHIFT >= 0 && MIN_ALLOCATION_SHIFT < PAGE_SIZE_SHIFT} incorrect minimal allocation shift`;
+    return MIN_ALLOCATION_SHIFT;
+})();
+export const MIN_ALLOCATION_LENGTH = PAGE_SIZE >> MIN_ALLOCATION_SHIFT;
+export const LAST_PAGE_NUMBER = (MEMORY_SIZE - PAGE_SIZE) / PAGE_SIZE;
+/** https://graypaper.fluffylabs.dev/#/68eaa1f/35a60235a602?v=0.6.4 */
+export const RESERVED_NUMBER_OF_PAGES = 16;
+/** https://graypaper.fluffylabs.dev/#/68eaa1f/35a60235a602?v=0.6.4 */
+export const MAX_NUMBER_OF_PAGES = MEMORY_SIZE / PAGE_SIZE;

package/packages/core/pvm-interpreter/memory/memory-index.d.ts

@@ -0,0 +1,6 @@
+import { type Opaque } from "#@typeberry/utils";
+export type MemoryIndex = Opaque<number, "memory index">;
+export declare const tryAsMemoryIndex: (index: number) => MemoryIndex;
+export type SbrkIndex = Opaque<number, "sbrk index">;
+export declare const tryAsSbrkIndex: (index: number) => SbrkIndex;
+//# sourceMappingURL=memory-index.d.ts.map

package/packages/core/pvm-interpreter/memory/memory-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-index.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/pvm-interpreter/memory/memory-index.ts"],"names":[],"mappings":"AACA,OAAO,EAAuB,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAEpE,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAEzD,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,KAAG,WAGhD,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AAErD,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,SAG9C,CAAC"}

package/packages/core/pvm-interpreter/memory/memory-index.js

@@ -0,0 +1,10 @@
+import { MAX_MEMORY_INDEX } from "#@typeberry/pvm-interface";
+import { asOpaqueType, check } from "#@typeberry/utils";
+export const tryAsMemoryIndex = (index) => {
+    check `${index >= 0 && index <= MAX_MEMORY_INDEX} Incorrect memory index: ${index}!`;
+    return asOpaqueType(index);
+};
+export const tryAsSbrkIndex = (index) => {
+    check `${index >= 0 && index <= MAX_MEMORY_INDEX + 1} Incorrect sbrk index: ${index}!`;
+    return asOpaqueType(index);
+};

package/packages/core/pvm-interpreter/memory/memory-range.d.ts

@@ -0,0 +1,43 @@
+import { type MemoryIndex } from "./memory-index.js";
+/**
+ * A representation of open-ended range of consecutive indices in memory,
+ * possibly empty or wrapping around.
+ *
+ * `[start, start + length)`
+ */
+export declare class MemoryRange {
+    readonly start: MemoryIndex;
+    readonly length: number;
+    /**
+     * Exclusive end index of the range.
+     *
+     * NOTE: The index may be wrapped around and smaller than `start`!
+     */
+    readonly end: MemoryIndex;
+    /**
+     * Inclusive last index of the range (present unless the range is empty).
+     *
+     * NOTE: the index may be wrapped around and smaller than `start`!
+     */
+    readonly lastIndex: MemoryIndex | null;
+    private constructor();
+    /** Creates a memory range from given starting point and length */
+    static fromStartAndLength(start: MemoryIndex, length: number): MemoryRange;
+    /** Checks if a range is empty (`length === 0`) */
+    isEmpty(): boolean;
+    /** Returns true if the range is wrapped (`start` >= `end`) and is not empty */
+    isWrapped(): boolean;
+    /** Checks if given memory address is within the range */
+    isInRange(address: MemoryIndex): boolean;
+    /** Checks if this range overlaps with another range */
+    overlapsWith(other: MemoryRange): boolean;
+}
+/**
+ * The first 16 pages of memory are reserved.
+ *
+ * https://graypaper.fluffylabs.dev/#/cc517d7/24d00024d000?v=0.6.5
+ *
+ * it should be in `memory-consts` but it cannot be there because of circular dependency
+ */
+export declare const RESERVED_MEMORY_RANGE: MemoryRange;
+//# sourceMappingURL=memory-range.d.ts.map

package/packages/core/pvm-interpreter/memory/memory-range.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-range.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/pvm-interpreter/memory/memory-range.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,WAAW,EAAoB,MAAM,mBAAmB,CAAC;AAEvE;;;;;GAKG;AACH,qBAAa,WAAW;aAeJ,KAAK,EAAE,WAAW;aAClB,MAAM,EAAE,MAAM;IAfhC;;;;OAIG;IACH,SAAgB,GAAG,EAAE,WAAW,CAAC;IACjC;;;;OAIG;IACH,SAAgB,SAAS,EAAE,WAAW,GAAG,IAAI,CAAQ;IAErD,OAAO;IAWP,kEAAkE;IAClE,MAAM,CAAC,kBAAkB,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM;IAQ5D,kDAAkD;IAClD,OAAO;IAIP,+EAA+E;IAC/E,SAAS;IAIT,yDAAyD;IACzD,SAAS,CAAC,OAAO,EAAE,WAAW;IAQ9B,uDAAuD;IACvD,YAAY,CAAC,KAAK,EAAE,WAAW;CAYhC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,aAGjC,CAAC"}

package/packages/core/pvm-interpreter/memory/memory-range.js

@@ -0,0 +1,73 @@
+import { MEMORY_SIZE } from "#@typeberry/pvm-interface";
+import { PAGE_SIZE, RESERVED_NUMBER_OF_PAGES } from "./memory-consts.js";
+import { tryAsMemoryIndex } from "./memory-index.js";
+/**
+ * A representation of open-ended range of consecutive indices in memory,
+ * possibly empty or wrapping around.
+ *
+ * `[start, start + length)`
+ */
+export class MemoryRange {
+    start;
+    length;
+    /**
+     * Exclusive end index of the range.
+     *
+     * NOTE: The index may be wrapped around and smaller than `start`!
+     */
+    end;
+    /**
+     * Inclusive last index of the range (present unless the range is empty).
+     *
+     * NOTE: the index may be wrapped around and smaller than `start`!
+     */
+    lastIndex = null;
+    constructor(start, length) {
+        this.start = start;
+        this.length = length;
+        this.end = tryAsMemoryIndex((this.start + this.length) % MEMORY_SIZE);
+        if (length > 0) {
+            this.lastIndex = tryAsMemoryIndex((this.end - 1 + MEMORY_SIZE) % MEMORY_SIZE);
+        }
+    }
+    /** Creates a memory range from given starting point and length */
+    static fromStartAndLength(start, length) {
+        if (!Number.isInteger(length) || length < 0 || length > MEMORY_SIZE) {
+            throw new TypeError(`length must be a non-negative integer and less than ${MEMORY_SIZE}, got ${length}`);
+        }
+        return new MemoryRange(start, length);
+    }
+    /** Checks if a range is empty (`length === 0`) */
+    isEmpty() {
+        return this.length === 0;
+    }
+    /** Returns true if the range is wrapped (`start` >= `end`) and is not empty */
+    isWrapped() {
+        return this.start >= this.end && !this.isEmpty();
+    }
+    /** Checks if given memory address is within the range */
+    isInRange(address) {
+        if (this.isWrapped()) {
+            return address >= this.start || address < this.end;
+        }
+        return address >= this.start && address < this.end;
+    }
+    /** Checks if this range overlaps with another range */
+    overlapsWith(other) {
+        if (this.lastIndex === null || other.lastIndex === null) {
+            return false;
+        }
+        return (this.isInRange(other.start) ||
+            this.isInRange(other.lastIndex) ||
+            other.isInRange(this.start) ||
+            other.isInRange(this.lastIndex));
+    }
+}
+/**
+ * The first 16 pages of memory are reserved.
+ *
+ * https://graypaper.fluffylabs.dev/#/cc517d7/24d00024d000?v=0.6.5
+ *
+ * it should be in `memory-consts` but it cannot be there because of circular dependency
+ */
+export const RESERVED_MEMORY_RANGE = MemoryRange.fromStartAndLength(tryAsMemoryIndex(0), RESERVED_NUMBER_OF_PAGES * PAGE_SIZE);

package/packages/core/pvm-interpreter/memory/memory-range.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=memory-range.test.d.ts.map

package/packages/core/pvm-interpreter/memory/memory-range.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-range.test.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/pvm-interpreter/memory/memory-range.test.ts"],"names":[],"mappings":""}

package/packages/core/pvm-interpreter/memory/memory-range.test.js

@@ -0,0 +1,180 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { MEMORY_SIZE } from "#@typeberry/pvm-interface";
+import { PAGE_SIZE } from "./memory-consts.js";
+import { tryAsMemoryIndex } from "./memory-index.js";
+import { MemoryRange } from "./memory-range.js";
+describe("MemoryRange", () => {
+    describe("create", () => {
+        it("should create a MemoryRange from addresses", () => {
+            const start = tryAsMemoryIndex(1 * PAGE_SIZE);
+            const length = PAGE_SIZE;
+            const expectedEnd = tryAsMemoryIndex(2 * PAGE_SIZE);
+            const memoryRange = MemoryRange.fromStartAndLength(start, length);
+            assert.strictEqual(memoryRange.start, start);
+            assert.strictEqual(memoryRange.end, expectedEnd);
+        });
+        it("should create a MemoryRange from starting point and length", () => {
+            const start = tryAsMemoryIndex(1);
+            const length = PAGE_SIZE;
+            const memoryRange = MemoryRange.fromStartAndLength(start, length);
+            assert.strictEqual(memoryRange.start, start);
+            assert.strictEqual(memoryRange.end, start + PAGE_SIZE);
+        });
+    });
+    describe("isEmpty", () => {
+        it("should return true for an empty range", () => {
+            const start = tryAsMemoryIndex(1 * PAGE_SIZE);
+            const length = 0;
+            const memoryRange = MemoryRange.fromStartAndLength(start, length);
+            assert.strictEqual(memoryRange.isEmpty(), true);
+        });
+        it("should return false for a non-empty range", () => {
+            const start = tryAsMemoryIndex(1 * PAGE_SIZE);
+            const length = PAGE_SIZE;
+            const memoryRange = MemoryRange.fromStartAndLength(start, length);
+            assert.strictEqual(memoryRange.isEmpty(), false);
+        });
+        it("should return false for full range", () => {
+            const start = tryAsMemoryIndex(0);
+            const length = MEMORY_SIZE;
+            const memoryRange = MemoryRange.fromStartAndLength(start, length);
+            assert.strictEqual(memoryRange.isEmpty(), false);
+        });
+    });
+    describe("isWrapped", () => {
+        it("should return true for a wrapped range", () => {
+            const start = tryAsMemoryIndex(2 * PAGE_SIZE);
+            const length = MEMORY_SIZE - 5;
+            const memoryRange = MemoryRange.fromStartAndLength(start, length);
+            assert.strictEqual(memoryRange.isWrapped(), true);
+        });
+        it("should return false for a non-wrapped range", () => {
+            const start = tryAsMemoryIndex(1 * PAGE_SIZE);
+            const length = PAGE_SIZE;
+            const memoryRange = MemoryRange.fromStartAndLength(start, length);
+            assert.strictEqual(memoryRange.isWrapped(), false);
+        });
+    });
+    describe("isInRange", () => {
+        it("should return true for a point in range (non-wrapped)", () => {
+            const start = tryAsMemoryIndex(1 * PAGE_SIZE);
+            const length = PAGE_SIZE + 1;
+            const address = tryAsMemoryIndex(2 * PAGE_SIZE);
+            const memoryRange = MemoryRange.fromStartAndLength(start, length);
+            assert.strictEqual(memoryRange.isInRange(address), true);
+        });
+        it("should return true for a point in range (wrapped)", () => {
+            const start = tryAsMemoryIndex(3 * PAGE_SIZE);
+            const length = MEMORY_SIZE - PAGE_SIZE;
+            const address = tryAsMemoryIndex(4 * PAGE_SIZE);
+            const memoryRange = MemoryRange.fromStartAndLength(start, length);
+            assert.strictEqual(memoryRange.isInRange(address), true);
+        });
+        it("should return false for a point not in range (non-wrapped)", () => {
+            const start = tryAsMemoryIndex(1 * PAGE_SIZE);
+            const length = PAGE_SIZE;
+            const address = tryAsMemoryIndex(3 * PAGE_SIZE);
+            const memoryRange = MemoryRange.fromStartAndLength(start, length);
+            assert.strictEqual(memoryRange.isInRange(address), false);
+        });
+        it("should return false for a point not in range (wrapped)", () => {
+            const start = tryAsMemoryIndex(3 * PAGE_SIZE);
+            const length = PAGE_SIZE;
+            const address = tryAsMemoryIndex(2 * PAGE_SIZE);
+            const memoryRange = MemoryRange.fromStartAndLength(start, length);
+            assert.strictEqual(memoryRange.isInRange(address), false);
+        });
+        it("should return false for an empty range", () => {
+            const start = tryAsMemoryIndex(1 * PAGE_SIZE);
+            const length = 0;
+            const address = tryAsMemoryIndex(1 * PAGE_SIZE);
+            const memoryRange = MemoryRange.fromStartAndLength(start, length);
+            assert.strictEqual(memoryRange.isInRange(address), false);
+        });
+        it("should return true for a point that is equal to `start`", () => {
+            const start = tryAsMemoryIndex(1 * PAGE_SIZE);
+            const length = PAGE_SIZE;
+            const address = tryAsMemoryIndex(1 * PAGE_SIZE);
+            const memoryRange = MemoryRange.fromStartAndLength(start, length);
+            assert.strictEqual(memoryRange.isInRange(address), true);
+        });
+        it("should return false for a point that is equal to `end`", () => {
+            const start = tryAsMemoryIndex(1 * PAGE_SIZE);
+            const length = PAGE_SIZE;
+            const address = tryAsMemoryIndex(2 * PAGE_SIZE);
+            const memoryRange = MemoryRange.fromStartAndLength(start, length);
+            assert.strictEqual(memoryRange.isInRange(address), false);
+        });
+        it("should return true for a point that is equal to `end - 1`", () => {
+            const start = tryAsMemoryIndex(1 * PAGE_SIZE);
+            const length = PAGE_SIZE;
+            const address = tryAsMemoryIndex(2 * PAGE_SIZE - 1);
+            const memoryRange = MemoryRange.fromStartAndLength(start, length);
+            assert.strictEqual(memoryRange.isInRange(address), true);
+        });
+    });
+    describe("overlapsWith", () => {
+        it("should return true for overlapping ranges", () => {
+            const range1 = MemoryRange.fromStartAndLength(tryAsMemoryIndex(1), 2);
+            const range2 = MemoryRange.fromStartAndLength(tryAsMemoryIndex(2), 2);
+            assert.strictEqual(range1.overlapsWith(range2), true);
+            assert.strictEqual(range2.overlapsWith(range1), true);
+        });
+        it("should return true for equal but not empty ranges", () => {
+            const range1 = MemoryRange.fromStartAndLength(tryAsMemoryIndex(1), 1);
+            const range2 = MemoryRange.fromStartAndLength(tryAsMemoryIndex(1), 1);
+            assert.strictEqual(range1.overlapsWith(range2), true);
+            assert.strictEqual(range2.overlapsWith(range1), true);
+        });
+        it("should return true for equal but not empty ranges (wrapped)", () => {
+            const range1 = MemoryRange.fromStartAndLength(tryAsMemoryIndex(3), MEMORY_SIZE - 1);
+            const range2 = MemoryRange.fromStartAndLength(tryAsMemoryIndex(3), MEMORY_SIZE - 1);
+            assert.strictEqual(range1.overlapsWith(range2), true);
+            assert.strictEqual(range2.overlapsWith(range1), true);
+        });
+        it("should return false for non-overlapping ranges", () => {
+            const range1 = MemoryRange.fromStartAndLength(tryAsMemoryIndex(1), 1);
+            const range2 = MemoryRange.fromStartAndLength(tryAsMemoryIndex(3), 1);
+            assert.strictEqual(range1.overlapsWith(range2), false);
+            assert.strictEqual(range2.overlapsWith(range1), false);
+        });
+        it("should return false for empty range", () => {
+            const range1 = MemoryRange.fromStartAndLength(tryAsMemoryIndex(2), 0);
+            const range2 = MemoryRange.fromStartAndLength(tryAsMemoryIndex(1), 3);
+            assert.strictEqual(range1.overlapsWith(range2), false);
+            assert.strictEqual(range2.overlapsWith(range1), false);
+        });
+        it("should return false when `end` of the first range is equal to `start` of the second range", () => {
+            const range1 = MemoryRange.fromStartAndLength(tryAsMemoryIndex(1), 1);
+            const range2 = MemoryRange.fromStartAndLength(tryAsMemoryIndex(2), 3);
+            assert.strictEqual(range1.overlapsWith(range2), false);
+            assert.strictEqual(range2.overlapsWith(range1), false);
+        });
+        it("should return false for non-overlapping ranges (wrapped)", () => {
+            const range1 = MemoryRange.fromStartAndLength(tryAsMemoryIndex(2), 2);
+            const range2 = MemoryRange.fromStartAndLength(tryAsMemoryIndex(4), MEMORY_SIZE - 2);
+            assert.strictEqual(range1.overlapsWith(range2), false);
+            assert.strictEqual(range2.overlapsWith(range1), false);
+        });
+        it("should return true when one range completely contains another", () => {
+            const outerRange = MemoryRange.fromStartAndLength(tryAsMemoryIndex(1), 4);
+            const innerRange = MemoryRange.fromStartAndLength(tryAsMemoryIndex(2), 2);
+            assert.strictEqual(outerRange.overlapsWith(innerRange), true);
+            assert.strictEqual(innerRange.overlapsWith(outerRange), true);
+        });
+        it("should return true for complex overlapping wrapped ranges", () => {
+            const range1 = MemoryRange.fromStartAndLength(tryAsMemoryIndex(3), MEMORY_SIZE - 2);
+            const range2 = MemoryRange.fromStartAndLength(tryAsMemoryIndex(4), MEMORY_SIZE - 2);
+            assert.strictEqual(range1.overlapsWith(range2), true);
+            assert.strictEqual(range2.overlapsWith(range1), true);
+        });
+        it("should return true for non empty and full ranges", () => {
+            const range1 = MemoryRange.fromStartAndLength(tryAsMemoryIndex(1), PAGE_SIZE);
+            const range2 = MemoryRange.fromStartAndLength(tryAsMemoryIndex(0), MEMORY_SIZE);
+            assert.strictEqual(range1.overlapsWith(range2), true);
+            assert.strictEqual(range2.overlapsWith(range1), true);
+        });
+    });
+    describe("getPageNumbers", () => { });
+});

package/packages/core/pvm-interpreter/memory/memory-utils.d.ts

@@ -0,0 +1,7 @@
+import { type MemoryIndex, type SbrkIndex } from "./memory-index.js";
+import { type PageNumber } from "./pages/page-utils.js";
+export declare function alignToPageSize(length: number): number;
+export declare function getPageNumber(address: MemoryIndex | SbrkIndex): number & import("@typeberry/utils").WithOpaque<"memory page number">;
+export declare function getStartPageIndex(address: MemoryIndex): number & import("@typeberry/utils").WithOpaque<"memory index">;
+export declare function getStartPageIndexFromPageNumber(pageNumber: PageNumber): number & import("@typeberry/utils").WithOpaque<"memory index">;
+//# sourceMappingURL=memory-utils.d.ts.map

package/packages/core/pvm-interpreter/memory/memory-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-utils.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/pvm-interpreter/memory/memory-utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAoB,MAAM,mBAAmB,CAAC;AACvF,OAAO,EAAE,KAAK,UAAU,EAAmB,MAAM,uBAAuB,CAAC;AAEzE,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,UAE7C;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,wEAE7D;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,kEAErD;AAED,wBAAgB,+BAA+B,CAAC,UAAU,EAAE,UAAU,kEAGrE"}

package/packages/core/pvm-interpreter/memory/memory-utils.js

@@ -0,0 +1,16 @@
+import { PAGE_SIZE, PAGE_SIZE_SHIFT } from "./memory-consts.js";
+import { tryAsMemoryIndex } from "./memory-index.js";
+import { tryAsPageNumber } from "./pages/page-utils.js";
+export function alignToPageSize(length) {
+    return PAGE_SIZE * Math.ceil(length / PAGE_SIZE);
+}
+export function getPageNumber(address) {
+    return tryAsPageNumber(address >>> PAGE_SIZE_SHIFT);
+}
+export function getStartPageIndex(address) {
+    return tryAsMemoryIndex((address >>> PAGE_SIZE_SHIFT) << PAGE_SIZE_SHIFT);
+}
+export function getStartPageIndexFromPageNumber(pageNumber) {
+    // >>> 0 is needed to avoid changing sign of the number
+    return tryAsMemoryIndex((pageNumber << PAGE_SIZE_SHIFT) >>> 0);
+}

package/packages/core/pvm-interpreter/memory/memory-utils.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=memory-utils.test.d.ts.map