@fluffylabs/anan-as 1.2.0 → 1.3.0-5cbd3aa

package/dist/build/js/assembly/memory.js

@@ -0,0 +1,482 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Inst } from "./instructions/utils";
+import { IntMath } from "./math";
+import { Access, Arena, PAGE_SIZE, PAGE_SIZE_SHIFT, Page, RawPage, RESERVED_MEMORY, RESERVED_PAGES, } from "./memory-page";
+import { portable } from "./portable";
+// @unmanaged
+export class MaybePageFault {
+    constructor() {
+        /** Accessing memory triggered a page fault. */
+        this.isFault = false;
+        /** The page fault was caused by invalid memory access (i.e. writing to read-only memory). */
+        this.isAccess = false;
+        /** Start memory index of a page that triggered the fault. */
+        this.fault = 0;
+    }
+}
+const EMPTY_UINT8ARRAY = new Uint8Array(0);
+const EMPTY_PAGE = new Page(Access.None, new RawPage(-1, EMPTY_UINT8ARRAY));
+class Chunks {
+    constructor() {
+        this.firstPageData = EMPTY_UINT8ARRAY;
+        this.firstPageOffset = 0;
+        this.secondPageData = EMPTY_UINT8ARRAY;
+        this.secondPageEnd = 0;
+    }
+}
+class PageResult {
+    constructor() {
+        this.page = EMPTY_PAGE;
+        this.relativeAddress = 0;
+    }
+}
+const MEMORY_SIZE = 4294967296;
+const MAX_MEMORY_ADDRESS = 4294967295;
+// Direct-mapped page cache for fast lookups.
+// Cache size must be a power of 2. 256 entries covers most working sets.
+const PAGE_CACHE_SHIFT = 8;
+const PAGE_CACHE_SIZE = 1 << PAGE_CACHE_SHIFT; // 256
+const PAGE_CACHE_MASK = PAGE_CACHE_SIZE - 1;
+class PageCache {
+    constructor() {
+        // Parallel arrays for cache: tags store the page index, entries store the page.
+        // A tag of 0xFFFFFFFF means empty (no valid page).
+        this.tags = new StaticArray(PAGE_CACHE_SIZE);
+        this.entries = new StaticArray(PAGE_CACHE_SIZE);
+        const empty = EMPTY_PAGE;
+        for (let i = 0; i < PAGE_CACHE_SIZE; i++) {
+            this.tags[i] = 0xffffffff;
+            this.entries[i] = empty;
+        }
+    }
+    lookup(pageIdx) {
+        const slot = pageIdx & PAGE_CACHE_MASK;
+        if (unchecked(this.tags[slot]) === pageIdx) {
+            return unchecked(this.entries[slot]);
+        }
+        return null;
+    }
+    insert(pageIdx, page) {
+        const slot = pageIdx & PAGE_CACHE_MASK;
+        // biome-ignore lint/suspicious/noAssignInExpressions: intentional AS pattern
+        unchecked((this.tags[slot] = pageIdx));
+        // biome-ignore lint/suspicious/noAssignInExpressions: intentional AS pattern
+        unchecked((this.entries[slot] = page));
+    }
+    clear() {
+        for (let i = 0; i < PAGE_CACHE_SIZE; i++) {
+            this.tags[i] = 0xffffffff;
+            this.entries[i] = EMPTY_PAGE;
+        }
+    }
+}
+__decorate([
+    inline
+], PageCache.prototype, "lookup", null);
+__decorate([
+    inline
+], PageCache.prototype, "insert", null);
+export class MemoryBuilder {
+    constructor(preAllocatePages = 0) {
+        this.pages = new Map();
+        this.arena = new Arena(preAllocatePages);
+    }
+    /** Allocates memory pages with given `access`, for given `address` and initialize with `zeroes` */
+    setEmpty(access, address, len) {
+        const endAddress = address + len;
+        for (let currentAddress = address; currentAddress < endAddress; currentAddress += PAGE_SIZE) {
+            this.getOrCreatePageForAddress(access, currentAddress);
+        }
+        return this;
+    }
+    /** Allocates memory pages with given `access`, for given `address` and writes there `data` */
+    setData(access, address, data) {
+        let currentAddress = address;
+        let currentData = data;
+        while (currentData.length > 0) {
+            const page = this.getOrCreatePageForAddress(access, currentAddress);
+            const relAddress = currentAddress % PAGE_SIZE;
+            const spaceInPage = PAGE_SIZE - relAddress;
+            const end = u32(currentData.length) < spaceInPage ? currentData.length : spaceInPage;
+            page.raw.data.set(currentData.subarray(0, end), relAddress);
+            // move to the next address to write
+            currentAddress = currentAddress + end;
+            currentData = currentData.subarray(end);
+        }
+        return this;
+    }
+    /** Returns memory page for given address (creates if not exists) */
+    getOrCreatePageForAddress(access, address) {
+        const pageIdx = u32(address >> PAGE_SIZE_SHIFT);
+        if (pageIdx < RESERVED_PAGES) {
+            throw new Error(`Attempting to allocate reserved page: ${pageIdx}`);
+        }
+        if (!this.pages.has(pageIdx)) {
+            const page = this.arena.acquire();
+            this.pages.set(pageIdx, new Page(access, page));
+        }
+        return this.pages.get(pageIdx);
+    }
+    build(sbrkAddress = RESERVED_MEMORY, maxHeapPointer = MAX_MEMORY_ADDRESS) {
+        return new Memory(this.arena, this.pages, sbrkAddress, maxHeapPointer);
+    }
+}
+export class Memory {
+    constructor(arena, pages = new Map(), sbrkAddress = 0, maxHeapPointer = MAX_MEMORY_ADDRESS) {
+        this.arena = arena;
+        this.pages = pages;
+        this.sbrkAddress = sbrkAddress;
+        this.pageResult = new PageResult();
+        this.chunksResult = new Chunks();
+        this.cache = new PageCache();
+        const sbrkPage = u32(sbrkAddress >> PAGE_SIZE_SHIFT);
+        if (sbrkPage < RESERVED_PAGES) {
+            throw new Error("sbrk within reserved memory is not allowed!");
+        }
+        this.lastAllocatedPage = pages.has(sbrkPage) ? sbrkPage : sbrkPage - 1;
+        this.maxHeapPointer = u64(maxHeapPointer);
+        // Pre-populate cache with all existing pages
+        // @ts-ignore: AS Map iterator has array-like behavior
+        const keys = pages.keys();
+        // @ts-ignore: AS Map iterator has array-like behavior
+        for (let i = 0; i < keys.length; i++) {
+            // @ts-ignore: AS Map iterator has array-like behavior
+            const key = keys[i];
+            this.cache.insert(key, pages.get(key));
+        }
+    }
+    pageDump(index) {
+        const cached = this.cache.lookup(index);
+        if (cached !== null) {
+            return cached.raw.data;
+        }
+        if (!this.pages.has(index)) {
+            return null;
+        }
+        const page = this.pages.get(index);
+        this.cache.insert(index, page);
+        return page.raw.data;
+    }
+    /**
+     * Returns the WASM linear memory pointer (byte offset) for the backing buffer of the page at `pageIndex`.
+     *
+     * Returns `0` if the page does not exist or is not readable (page/access fault).
+     *
+     * This enables efficient memory reading on the JS side without extra WASM allocations:
+     * ```ts
+     * let pagesRead = 0;
+     * for (let address = start; address < end; address += PAGE_SIZE) {
+     *   const page = address >> PAGE_SIZE_SHIFT;
+     *   const ptr = getPagePointer(page);
+     *   if (ptr === 0) {
+     *     throw new Error(`Page fault at ${page << PAGE_SIZE_SHIFT}`);
+     *   }
+     *   destination.set(
+     *     new Uint8Array(wasm.instance.exports.memory.buffer, ptr, Math.min(end - address, PAGE_SIZE)),
+     *     pagesRead << PAGE_SIZE_SHIFT,
+     *   );
+     *   pagesRead += 1;
+     * }
+     * ```
+     */
+    getPagePointer(pageIndex) {
+        let page = this.cache.lookup(pageIndex);
+        if (page === null) {
+            if (!this.pages.has(pageIndex)) {
+                return 0;
+            }
+            page = this.pages.get(pageIndex);
+            this.cache.insert(pageIndex, page);
+        }
+        if (!page.can(Access.Read)) {
+            return 0;
+        }
+        // Trigger lazy allocation if the backing buffer has not been created yet.
+        // @ts-ignore: dataStart is an AS-specific property on Uint8Array
+        return page.raw.data.dataStart;
+    }
+    free() {
+        // @ts-ignore: AS returns T[], JS returns iterator - asArray handles both
+        const pages = portable.asArray(this.pages.values());
+        for (let i = 0; i < pages.length; i++) {
+            this.arena.release(pages[i].raw);
+        }
+        this.pages.clear();
+        this.cache.clear();
+    }
+    sbrk(faultRes, amount) {
+        const freeMemoryStart = u64(this.sbrkAddress);
+        if (amount === 0) {
+            faultRes.isFault = false;
+            return freeMemoryStart;
+        }
+        const newSbrk = portable.u64_add(freeMemoryStart, u64(amount));
+        if (newSbrk > this.maxHeapPointer) {
+            faultRes.isFault = true;
+            return freeMemoryStart;
+        }
+        this.sbrkAddress = u32(newSbrk);
+        const pageIdx = i32(portable.u64_sub(newSbrk, u64(1)) >> u64(PAGE_SIZE_SHIFT));
+        if (pageIdx === this.lastAllocatedPage) {
+            faultRes.isFault = false;
+            return freeMemoryStart;
+        }
+        for (let i = this.lastAllocatedPage + 1; i <= pageIdx; i++) {
+            const rawPage = this.arena.acquire();
+            const page = new Page(Access.Write, rawPage);
+            this.pages.set(i, page);
+            this.cache.insert(i, page);
+        }
+        this.lastAllocatedPage = pageIdx;
+        faultRes.isFault = false;
+        return freeMemoryStart;
+    }
+    getU8(faultRes, address) {
+        return u64(u8(this.getBytesReversed(faultRes, Access.Read, address, 1)));
+    }
+    getU16(faultRes, address) {
+        return u64(portable.bswap_u16(u16(this.getBytesReversed(faultRes, Access.Read, address, 2))));
+    }
+    getU32(faultRes, address) {
+        return u64(portable.bswap_u32(u32(this.getBytesReversed(faultRes, Access.Read, address, 4))));
+    }
+    getU64(faultRes, address) {
+        return portable.bswap_u64(this.getBytesReversed(faultRes, Access.Read, address, 8));
+    }
+    getI8(faultRes, address) {
+        return Inst.u8SignExtend(u8(this.getU8(faultRes, address)));
+    }
+    getI16(faultRes, address) {
+        return Inst.u16SignExtend(u16(this.getU16(faultRes, address)));
+    }
+    getI32(faultRes, address) {
+        return Inst.u32SignExtend(u32(this.getU32(faultRes, address)));
+    }
+    setU8(faultRes, address, value) {
+        this.setBytes(faultRes, address, value, 1);
+    }
+    setU16(faultRes, address, value) {
+        this.setBytes(faultRes, address, value, 2);
+    }
+    setU32(faultRes, address, value) {
+        this.setBytes(faultRes, address, value, 4);
+    }
+    setU64(faultRes, address, value) {
+        this.setBytes(faultRes, address, value, 8);
+    }
+    /**
+     * DO NOT USE.
+     *
+     * @deprecated exposed temporarily for debugger/typeberry API.
+     */
+    getMemory(fault, address, length) {
+        // first traverse memory and see if we don't page fault
+        if (length > 0) {
+            let nextAddress = address;
+            const pagesToCheck = i32(portable.u64_add(u64(length), u64(PAGE_SIZE - 1)) >> u64(PAGE_SIZE_SHIFT));
+            for (let page = 0; page < pagesToCheck; page++) {
+                const pageData = this.pageResult;
+                this.getPage(fault, pageData, Access.Read, nextAddress);
+                if (fault.isFault) {
+                    return null;
+                }
+                nextAddress += PAGE_SIZE;
+            }
+        }
+        // only after, actually allocate and read the bytes.
+        const destination = new Uint8Array(length);
+        this.bytesRead(fault, address, destination, 0);
+        if (fault.isFault) {
+            return null;
+        }
+        return destination;
+    }
+    bytesRead(faultRes, address, destination, destinationOffset) {
+        let nextAddress = address;
+        let destinationIndex = i32(destinationOffset);
+        while (destinationIndex < destination.length) {
+            const bytesLeft = destination.length - destinationIndex;
+            const pageData = this.pageResult;
+            this.getPage(faultRes, pageData, Access.Read, nextAddress);
+            if (faultRes.isFault) {
+                return;
+            }
+            const relAddress = pageData.relativeAddress;
+            const bytesToRead = relAddress + bytesLeft < PAGE_SIZE ? bytesLeft : PAGE_SIZE - pageData.relativeAddress;
+            // actually copy the bytes
+            const pageEnd = relAddress + bytesToRead;
+            const data = pageData.page.raw.data;
+            for (let i = relAddress; i < pageEnd; i++) {
+                destination[destinationIndex] = data[i];
+                destinationIndex++;
+            }
+            // move the pointers
+            nextAddress += bytesToRead;
+        }
+        return;
+    }
+    /** Write bytes from given `source` (with `sourceOffset`) at given `address`. */
+    bytesWrite(faultRes, address, source, sourceOffset) {
+        let nextAddress = address;
+        let sourceIndex = i32(sourceOffset);
+        while (sourceIndex < source.length) {
+            const bytesLeft = source.length - sourceIndex;
+            const pageData = this.pageResult;
+            this.getPage(faultRes, pageData, Access.Write, nextAddress);
+            if (faultRes.isFault) {
+                return;
+            }
+            const relAddress = pageData.relativeAddress;
+            const bytesToWrite = relAddress + bytesLeft < PAGE_SIZE ? bytesLeft : PAGE_SIZE - pageData.relativeAddress;
+            // actually copy the bytes
+            const pageEnd = relAddress + bytesToWrite;
+            const data = pageData.page.raw.data;
+            for (let i = relAddress; i < pageEnd; i++) {
+                data[i] = source[sourceIndex];
+                sourceIndex++;
+            }
+            // move the pointers
+            nextAddress += bytesToWrite;
+        }
+        return;
+    }
+    getPage(faultRes, pageData, access, address) {
+        const pageIdx = u32(address >> PAGE_SIZE_SHIFT);
+        const relAddress = address & (PAGE_SIZE - 1);
+        // Fast path: check cache first
+        const cached = this.cache.lookup(pageIdx);
+        if (cached !== null) {
+            if (!cached.can(access)) {
+                fault(faultRes, pageIdx << PAGE_SIZE_SHIFT);
+                faultRes.isAccess = true;
+                pageData.page = EMPTY_PAGE;
+                pageData.relativeAddress = relAddress;
+                return;
+            }
+            faultRes.isFault = false;
+            pageData.page = cached;
+            pageData.relativeAddress = relAddress;
+            return;
+        }
+        // Slow path: check Map
+        if (!this.pages.has(pageIdx)) {
+            fault(faultRes, pageIdx << PAGE_SIZE_SHIFT);
+            pageData.page = EMPTY_PAGE;
+            pageData.relativeAddress = relAddress;
+            return;
+        }
+        const page = this.pages.get(pageIdx);
+        // Insert into cache for next time
+        this.cache.insert(pageIdx, page);
+        if (!page.can(access)) {
+            fault(faultRes, pageIdx << PAGE_SIZE_SHIFT);
+            faultRes.isAccess = true;
+            pageData.page = EMPTY_PAGE;
+            pageData.relativeAddress = relAddress;
+            return;
+        }
+        faultRes.isFault = false;
+        pageData.page = page;
+        pageData.relativeAddress = relAddress;
+        return;
+    }
+    getChunks(faultRes, chunks, access, address, bytes) {
+        /**
+         * Accessing empty set of bytes is always valid.
+         * https://graypaper.fluffylabs.dev/#/68eaa1f/24a80024a800?v=0.6.4
+         */
+        if (bytes === 0) {
+            faultRes.isFault = false;
+            chunks.firstPageData = EMPTY_UINT8ARRAY;
+            chunks.firstPageOffset = 0;
+            chunks.secondPageData = EMPTY_UINT8ARRAY;
+            chunks.secondPageEnd = 0;
+            return;
+        }
+        const pageData = this.pageResult;
+        this.getPage(faultRes, pageData, access, address);
+        if (faultRes.isFault) {
+            return;
+        }
+        const page = pageData.page;
+        const relativeAddress = pageData.relativeAddress;
+        const endAddress = relativeAddress + u32(bytes);
+        const needSecondPage = endAddress > PAGE_SIZE;
+        // everything is on one page - easy case
+        if (!needSecondPage) {
+            chunks.firstPageData = page.raw.data;
+            chunks.firstPageOffset = relativeAddress;
+            return;
+        }
+        const secondPageIdx = u32((address + u32(bytes)) % MEMORY_SIZE) >> PAGE_SIZE_SHIFT;
+        const secondPageStart = secondPageIdx << PAGE_SIZE_SHIFT;
+        // Try cache first for second page
+        let secondPage = this.cache.lookup(secondPageIdx);
+        if (secondPage === null) {
+            if (!this.pages.has(secondPageIdx)) {
+                fault(faultRes, secondPageStart);
+                return;
+            }
+            secondPage = this.pages.get(secondPageIdx);
+            this.cache.insert(secondPageIdx, secondPage);
+        }
+        if (!secondPage.can(access)) {
+            fault(faultRes, secondPageStart);
+            faultRes.isAccess = true;
+            return;
+        }
+        chunks.firstPageData = page.raw.data;
+        chunks.firstPageOffset = relativeAddress;
+        chunks.secondPageData = secondPage.raw.data;
+        chunks.secondPageEnd = relativeAddress + u32(bytes) - PAGE_SIZE;
+        return;
+    }
+    /** Write some bytes to at most 2 pages. */
+    setBytes(faultRes, address, value, bytes) {
+        const r = this.chunksResult;
+        this.getChunks(faultRes, r, Access.Write, address, bytes);
+        if (faultRes.isFault) {
+            return;
+        }
+        let bytesLeft = u64(value);
+        // write to first page
+        const firstPageEnd = IntMath.minU32(PAGE_SIZE, r.firstPageOffset + bytes);
+        for (let i = r.firstPageOffset; i < firstPageEnd; i++) {
+            r.firstPageData[i] = u8(bytesLeft);
+            bytesLeft >>= u64(8);
+        }
+        // write rest to the second page
+        for (let i = 0; i < r.secondPageEnd; i++) {
+            r.secondPageData[i] = u8(bytesLeft);
+            bytesLeft >>= u64(8);
+        }
+    }
+    getBytesReversed(faultRes, access, address, bytes) {
+        this.getChunks(faultRes, this.chunksResult, access, address, bytes);
+        if (faultRes.isFault) {
+            return u64(0);
+        }
+        // result (bytes in reverse order)
+        let r = u64(0);
+        const firstPageEnd = IntMath.minU32(PAGE_SIZE, this.chunksResult.firstPageOffset + bytes);
+        // read from first page
+        for (let i = this.chunksResult.firstPageOffset; i < firstPageEnd; i++) {
+            r = (r << u64(8)) | u64(this.chunksResult.firstPageData[i]);
+        }
+        // read from the second page
+        for (let i = 0; i < this.chunksResult.secondPageEnd; i++) {
+            r = (r << u64(8)) | u64(this.chunksResult.secondPageData[i]);
+        }
+        return r;
+    }
+}
+function fault(r, address) {
+    r.isFault = true;
+    r.isAccess = false;
+    r.fault = address;
+}

package/dist/build/js/assembly/portable.d.ts

@@ -0,0 +1,24 @@
+export declare class portable {
+    static installPolyfills(): void;
+    static asArray<T>(v: T[]): T[];
+    static arrayAt<T>(v: T[], i: u32): T;
+    static staticArrayAt<T>(v: StaticArray<T>, i: u32): T;
+    static asU32(v: u32): u32;
+    static uint8ArrayView(data: ArrayBuffer, offset: i32, length: i32): Uint8Array;
+    static bswap_u16(v: u16): u16;
+    static bswap_u32(v: u32): u32;
+    static bswap_u64(v: u64): u64;
+    static popcnt_u32(v: u32): u32;
+    static popcnt_u64(v: u64): u64;
+    static clz_u32(v: u32): u32;
+    static clz_u64(v: u64): u64;
+    static ctz_u32(v: u32): u32;
+    static ctz_u64(v: u64): u64;
+    static rotr_u32(v: u32, shift: u32): u32;
+    static rotr_u64(v: u64, shift: u64): u64;
+    static rotl_u32(v: u32, shift: u32): u32;
+    static rotl_u64(v: u64, shift: u64): u64;
+    static u64_add(a: u64, b: u64): u64;
+    static u64_sub(a: u64, b: u64): u64;
+    static u64_mul(a: u64, b: u64): u64;
+}