quickwin 1.2.1 → 2.0.0

package/lib/ffi/struct.js

@@ -0,0 +1,412 @@
+import * as ffi from 'ffi';
+import '../text-codec.js';
+import { isCPtrToken, normToken, PTR_SIZE, PtrArrayBuffer, readScalar, SizeAlign, writeScalar, } from './ctype.js';
+// ============================================================
+// Layout IR —— computeStructLayout/lower 把 CType AST IR lower 到此。
+// 自包含：子布局在 lowering 时内嵌、offset 相对本层起点，运行期 read/write 不回查 AST IR。
+// ============================================================
+/** 向上对齐（a 必须是 2 的幂）。 */
+function alignUp(v, a) {
+    return (v + a - 1) & ~(a - 1);
+}
+// 归一后 token 的档位检查：'void'/指针 token 查表为 undefined（SizeAlign 只收 C_Number）。
+const isCNumberToken = (t) => SizeAlign[t] !== undefined;
+// 值 → { size, align, FieldType }：字符串先试字符串糖/数组糖/位域糖，再按 token 归一；
+// 对象值一律按 '#' 分派 —— 无「裸嵌套 map 默认 struct」，漏写 '#' 直接报错。
+// 字符串无 '#' 声明形式（词汇只有糖，见 ctype.ts §4）：旧写法落到末尾 unknown '#' 报错。
+function lower(v) {
+    if (typeof v === 'string') {
+        const st = /^(u8|u16)\[(\d+)\]@(utf-8|utf-16le)$/.exec(v); // 'u16[128]@utf-16le' → 字符串糖
+        if (st) {
+            const length = Number(st[2]);
+            if (!Number.isInteger(length) || length < 1)
+                throw new Error(`ffi-struct: string length must be an integer >= 1, got ${length}`);
+            // 布局 = unit × length（与 encoding 无关），encoding 只是读写时的解释 ——
+            // 'u8[128]@utf-16le'（128 字节按 utf-16le 解出 64 字符）之类的错配语义自洽。
+            const s = st[1] === 'u8' ? 1 : 2;
+            return { size: s * length, align: s, type: { tag: 'string', encoding: st[3] } };
+        }
+        const a = /^([^\[\]]+)\[(\d+)\]$/.exec(v); // 'u32[4]' / 'i3z[4]' → 数组糖（元素递归归一）
+        if (a) {
+            const length = Number(a[2]);
+            if (!Number.isInteger(length) || length < 1)
+                throw new Error(`ffi-struct: array length must be an integer >= 1, got ${length}`);
+            const el = lower(a[1]);
+            if (el.type.tag === 'bitfield')
+                throw new Error('ffi-struct: bitfields cannot be array elements');
+            return {
+                size: el.size * length,
+                align: el.align,
+                type: { tag: 'array', elementType: el.type, elementSize: el.size },
+            };
+        }
+        const b = /^([A-Za-z_]\w*):(\d+)$/.exec(v); // 'u32:3' → 位域糖（'f32:3' 归一后非整数档被拒）
+        if (b) {
+            const rawUnit = b[1];
+            const unit = normToken(rawUnit);
+            // 'void'/'<>ptr' 查表为 undefined、'float' 等别名 normToken 直接抛 —— 都不是合法位域单元。
+            if (!isCNumberToken(unit) || unit === 'f32' || unit === 'f64')
+                throw new Error(`ffi-struct: bitfield unit must be an integer type, got "${rawUnit}"`);
+            const width = Number(b[2]);
+            const s = SizeAlign[unit];
+            const cap = s * 8;
+            if (!Number.isInteger(width) || width < 1)
+                throw new Error(`ffi-struct: bitfield width must be an integer >= 1, got ${width}`);
+            if (width > cap)
+                throw new Error(`ffi-struct: bitfield width ${width} exceeds unit width ${cap}`);
+            // bit 是单元内偏移，由 computeStructLayout 的位域状态机填写；这里占位 0。
+            return { size: s, align: s, type: { tag: 'bitfield', unit, bit: 0, width } };
+        }
+        // 规范 token / 指针 token（别名机制已移除：'DWORD' 等 normToken 直接抛）。
+        // 归一后必须先判指针形，否则落 unknown kind；'void' 归一后无大小、
+        // 裸 'ptr'/'i3z' 未知 —— 都在这里抛（原先由 SizeAlign 查表兜住，现归一并入）。
+        const k = normToken(v);
+        if (isCPtrToken(k))
+            return { size: PTR_SIZE, align: PTR_SIZE, type: { tag: 'basic', kind: 'ptr' } };
+        if (!isCNumberToken(k))
+            throw new Error(`ffi-struct: unknown kind "${v}"`);
+        const s = SizeAlign[k];
+        return { size: s, align: s, type: { tag: 'basic', kind: k } };
+    }
+    if (v && typeof v === 'object') {
+        const o = v;
+        const tag = o['#'];
+        if (tag === undefined)
+            throw new Error(`ffi-struct: nested object value requires a '#' key ('struct' | 'union' | 'array')`);
+        if (tag === 'array' && '#pack' in o)
+            throw new Error(`ffi-struct: '#pack' is only allowed on struct/union, got '${tag}'`);
+        if (tag === 'array') {
+            const length = o['length'];
+            if (!Number.isInteger(length) || length < 1)
+                throw new Error(`ffi-struct: array length must be an integer >= 1, got ${String(length)}`);
+            const el = lower(o['element']);
+            if (el.type.tag === 'bitfield')
+                throw new Error('ffi-struct: bitfields cannot be array elements');
+            return {
+                size: el.size * length,
+                align: el.align,
+                type: { tag: 'array', elementType: el.type, elementSize: el.size },
+            };
+        }
+        if (tag === 'struct' || tag === 'union') {
+            const l = computeStructLayout(v);
+            return { size: l.size, align: l.maxEffectiveAlign, type: { tag, fields: l.fields } };
+        }
+        throw new Error(`ffi-struct: unknown '#' declaration ${JSON.stringify(String(tag))}`);
+    }
+    throw new Error(`ffi-struct: invalid member value: ${String(v)}`);
+}
+export function computeArray(t) {
+    const { size, align } = lower(t);
+    return { align, size };
+}
+export function computeStructLayout(t) {
+    const isStruct = t['#'] === 'struct';
+    const pack = t['#pack'] ?? 8;
+    let maxEffectiveAlign = 1;
+    let maxMemberSize = 0;
+    const fields = [];
+    let cursor = 0;
+    // 位域组状态：unitBase 是当前存储单元的字节基址（-1 = 不在位域组内），
+    // unitBits 是单元内已用位数，unitSize 是单元宽（字节）。
+    // MSVC 规则（mingw 交叉实测 DCB/COMSTAT 验证）：
+    //   - 连续同宽位域共单元，LSB→MSB（签别不参与分组）
+    //   - 放不下的位域开新单元，单元剩余位废弃
+    //   - 非位域成员打断位域组，游标跳到完整单元边界（不是按字节截断）
+    // 联合体位域不分组：每位域成员独立从 offset 0/bit 0 起算——完全别名
+    // （mingw 16 x64+ia32 实测：a=1→b=1、溢出成员回 offset 0、sizeof=单元宽）。
+    let unitBase = -1;
+    let unitBits = 0;
+    let unitSize = 0;
+    // 落定当前位域组：游标 = 单元起点 + 已用字节数，向上取整到单元宽。
+    const flushUnit = () => {
+        if (unitBase < 0)
+            return;
+        cursor = alignUp(unitBase + Math.ceil(unitBits / 8), unitSize);
+        unitBase = -1;
+    };
+    for (const [rawName, v] of Object.entries(t)) {
+        if (rawName.startsWith('#'))
+            continue; // '#' 指令键（'#'/'#pack'）不是字段
+        const m = /^([^@]+)@(\d+)$/.exec(rawName); // 键尾 '@N' = alignas（字段名不含 '@'）
+        const name = m ? m[1] : rawName;
+        const alignas = m ? Number(m[2]) : 0;
+        const { size, align: natural, type } = lower(v);
+        // '!' 非空担保标记（原文 `<X>ptr!`）：lower 里 normToken 已拒掉 'u32!'/'HANDLE!' 等
+        // 非法尾缀，能走到这里的 '!' 尾必是指针 token —— 记到 Field 上供 decode 的 0 断言。
+        const nonnull = typeof v === 'string' && v.endsWith('!');
+        let align = natural;
+        if (pack > 0)
+            align = Math.min(pack, align);
+        if (alignas)
+            align = Math.max(align, alignas);
+        if (type.tag === 'bitfield') {
+            if (name.startsWith('$'))
+                throw new Error('ffi-struct: bitfield members must be named');
+            // union：成员同址（C 标准），每位域成员独立从 offset 0/bit 0 起算。
+            // 不顺序分组、不开新单元、不动游标（flushUnit 因 unitBase 恒 -1 而
+            // no-op，普通/匿名成员的 offset 也因此保持 0）——曾因游标推进致
+            // 溢出单元/后续成员落在 union 声明 size 之外（越界读写）。
+            if (!isStruct) {
+                fields.push({ name: name, offset: 0, size, type: { ...type, bit: 0 } });
+                maxEffectiveAlign = Math.max(maxEffectiveAlign, align);
+                maxMemberSize = Math.max(maxMemberSize, size);
+                continue;
+            }
+            const width = type.width;
+            // 新单元：无活动单元 / 单元宽不同 / 放不下。
+            if (unitBase < 0 || size !== unitSize || unitBits + width > unitSize * 8) {
+                // 单元宽变化或溢出时先把旧单元落定，新单元从落定点对齐。
+                if (unitBase >= 0)
+                    flushUnit();
+                const offset = alignUp(cursor, align);
+                unitBase = offset;
+                unitBits = 0;
+                unitSize = size;
+            }
+            fields.push({
+                name: name,
+                offset: unitBase, // 单元基址（不是位域自己的地址）
+                size,
+                type: { ...type, bit: unitBits },
+            });
+            unitBits += width;
+            maxEffectiveAlign = Math.max(maxEffectiveAlign, align);
+            maxMemberSize = Math.max(maxMemberSize, size);
+            continue;
+        }
+        flushUnit();
+        const offset = alignUp(cursor, align);
+        if (!name.startsWith('$')) {
+            fields.push({ name: name, offset, size, type, ...(nonnull ? { nonnull: true } : {}) });
+        }
+        else {
+            // 匿名聚合：内嵌 fields 已 lower 好，offset 平移到本成员起点。
+            if (type.tag !== 'struct' && type.tag !== 'union')
+                throw new Error(`ffi-struct: anonymous member "${name}" must be a struct/union`);
+            for (const cf of type.fields)
+                fields.push({ ...cf, offset: cf.offset + offset });
+        }
+        if (isStruct)
+            cursor = offset + size;
+        maxEffectiveAlign = Math.max(maxEffectiveAlign, align);
+        maxMemberSize = Math.max(maxMemberSize, size);
+    }
+    flushUnit();
+    return {
+        size: isStruct ? alignUp(cursor, maxEffectiveAlign) : alignUp(maxMemberSize, maxEffectiveAlign),
+        maxEffectiveAlign,
+        fields,
+    };
+}
+function readUnitRaw(dv, off, unit) {
+    const s = SizeAlign[unit];
+    if (s === 1)
+        return BigInt(dv.getUint8(off));
+    if (s === 2)
+        return BigInt(dv.getUint16(off, true));
+    if (s === 4)
+        return BigInt(dv.getUint32(off, true));
+    return dv.getBigUint64(off, true);
+}
+function writeUnitRaw(dv, off, unit, v) {
+    const s = SizeAlign[unit];
+    if (s === 1) {
+        dv.setUint8(off, Number(v & 0xffn));
+        return;
+    }
+    if (s === 2) {
+        dv.setUint16(off, Number(v & 0xffffn), true);
+        return;
+    }
+    if (s === 4) {
+        dv.setUint32(off, Number(v & 0xffffffffn), true);
+        return;
+    }
+    dv.setBigUint64(off, v & 0xffffffffffffffffn, true);
+}
+function readBitfield(dv, off, t) {
+    const w = BigInt(t.width);
+    let v = (readUnitRaw(dv, off, t.unit) >> BigInt(t.bit)) & ((1n << w) - 1n);
+    if (t.unit[0] === 'i' && (v & (1n << (w - 1n)))) // 有符号单元且符号位为 1 → 先符号扩展
+        v -= 1n << w;
+    if (t.width > 53)
+        return v; // 值域装不进安全整数 → bigint（与类型层 BitShape 同界）
+    return Number(v);
+}
+function writeBitfield(dv, off, t, val) {
+    const w = BigInt(t.width);
+    const bit = BigInt(t.bit);
+    const widthMask = (1n << w) - 1n;
+    const posMask = widthMask << bit;
+    const raw = readUnitRaw(dv, off, t.unit);
+    const bits = (typeof val === 'bigint' ? val : BigInt(Math.trunc(val))) & widthMask;
+    writeUnitRaw(dv, off, t.unit, (raw & ~posMask) | (bits << bit));
+}
+// 字符串读写统一走 TextEncoder/TextDecoder（polyfill 见 lib/text-codec.js）。
+const stringEncoders = {
+    'utf-8': new TextEncoder('utf-8'),
+    'utf-16le': new TextEncoder('utf-16le'),
+};
+const stringDecoders = {
+    'utf-8': new TextDecoder('utf-8', { ignoreBOM: true }),
+    'utf-16le': new TextDecoder('utf-16le', { ignoreBOM: true }),
+};
+function readString(dv, off, size, enc) {
+    const bytes = new Uint8Array(dv.buffer, dv.byteOffset + off, size);
+    const unit = enc === 'utf-16le' ? 2 : 1;
+    let end = size;
+    for (let i = 0; i + unit <= size; i += unit) {
+        if (bytes[i] === 0 && (unit === 1 || bytes[i + 1] === 0)) {
+            end = i;
+            break;
+        }
+    }
+    return stringDecoders[enc].decode(bytes.subarray(0, end));
+}
+function writeString(dv, off, size, enc, v) {
+    const bytes = new Uint8Array(dv.buffer, dv.byteOffset + off, size);
+    bytes.fill(0);
+    // 始终给 NUL 终止符留一个存储单元（宽度由 encoding 决定，见 readString）：
+    // 末尾保持 0，payload 最多 size - unit 字节。这样 C 侧 strlen/wcslen 都不会越界。
+    const unit = enc === 'utf-16le' ? 2 : 1;
+    const cap = size - unit;
+    if (cap <= 0)
+        return;
+    const src = stringEncoders[enc].encode(String(v ?? ''));
+    bytes.set(src.subarray(0, Math.min(src.length, cap)));
+}
+function readArray(dv, off, size, t) {
+    const count = t.elementSize > 0 ? size / t.elementSize : 0;
+    const out = [];
+    for (let i = 0; i < count; i++)
+        out.push(readElement(dv, off + i * t.elementSize, t.elementType, t.elementSize));
+    return out;
+}
+function writeArray(dv, off, size, t, v) {
+    const count = t.elementSize > 0 ? size / t.elementSize : 0;
+    const list = (v ?? []);
+    for (let i = 0; i < count; i++)
+        writeElement(dv, off + i * t.elementSize, t.elementType, t.elementSize, list[i]);
+}
+function readElement(dv, off, t, size) {
+    switch (t.tag) {
+        case 'basic': return readScalar(dv, off, t.kind);
+        case 'bitfield': return readBitfield(dv, off, t);
+        case 'string': return readString(dv, off, size, t.encoding);
+        case 'struct':
+        case 'union': return doDecode(dv, off, t.fields);
+        case 'array': return readArray(dv, off, size, t);
+    }
+}
+function writeElement(dv, off, t, size, val) {
+    switch (t.tag) {
+        // TODO: remove this any
+        case 'basic':
+            writeScalar(dv, off, { k: t.kind, v: val });
+            break;
+        // 直传（不 Number()）：writeBitfield 的 val 是 number | bigint，
+        // 64 位单元走 bigint，先 Number() 会把 >2^53 的位域值截断。
+        case 'bitfield':
+            writeBitfield(dv, off, t, (val ?? 0));
+            break;
+        case 'string':
+            writeString(dv, off, size, t.encoding, val);
+            break;
+        case 'struct':
+        case 'union':
+            doEncode(dv, off, t.fields, (val ?? {}));
+            break;
+        case 'array':
+            writeArray(dv, off, size, t, val);
+            break;
+    }
+}
+function doDecode(dv, base, fields) {
+    const out = {};
+    for (const f of fields) {
+        const v = readElement(dv, base + f.offset, f.type, f.size);
+        // '!' 非空担保的后置兜底：C 没填（忘判成功就 decode）或拿未填充槽（decode(alloc())）
+        // 读出 0 —— 当场 throw，不让 0 带 Ptr 品牌流到下游 '! 消费位'。成功路径必非零，不触发。
+        if (f.nonnull && v === 0)
+            throw new Error(`ffi-struct: decode: '!' field "${f.name}" got 0 ` +
+                `(C did not fill it, or decode was called on an unfilled slot)`);
+        out[f.name] = v;
+    }
+    return out;
+}
+function doEncode(dv, base, fields, v) {
+    for (const f of fields) {
+        // DeepPartial 缺省：不动该字段（新建 buffer 上保持 0、复用 buffer 上保留旧值）；
+        // 嵌套/数组字段整个缺失也在这里拦下（writeElement 的 struct 分支回到本函数）。
+        if (v[f.name] === undefined)
+            continue;
+        writeElement(dv, base + f.offset, f.type, f.size, v[f.name]);
+    }
+}
+// ============================================================
+// 内部构造器
+// ============================================================
+function createStruct(t) {
+    const { fields, size, maxEffectiveAlign } = computeStructLayout(t);
+    return {
+        __struct: t,
+        size,
+        structAlign: maxEffectiveAlign,
+        decode: (p) => {
+            // number = native 拥有的品牌指针（Codec 的 decode(p) 形态）：按布局 size
+            // 逐字节拷进临时 buffer 再解码；ArrayBuffer = 调用方持有的 out buffer 直读。
+            // 顶层不收 offset——out 参数恒从起点读，嵌套偏移由字段布局（doDecode 的 base）承担。
+            if (typeof p === 'number') {
+                const buf = new ArrayBuffer(size);
+                const u8 = new Uint8Array(buf);
+                for (let i = 0; i < size; i++)
+                    u8[i] = ffi.readByte(p + i);
+                return doDecode(new DataView(buf), 0, fields);
+            }
+            return doDecode(new DataView(p), 0, fields);
+        },
+        alloc: (() => new PtrArrayBuffer(size)),
+        encode: ((v, buf) => {
+            // fail-loud：无参 = 分配语义，走 alloc()；这里绝不静默零填充 —— 类型层由
+            // EncodeIn 拦 '!' 字段省略，动态/JS 调用方由本 throw 兜住。顶层不收 offset
+            // （与 decode 对齐，见 StructDef 注释），恒从 buffer 起点写。
+            if (v === undefined || v === null)
+                throw new Error(`ffi-struct: encode(v) requires an argument; ` +
+                    `use alloc() for a zeroed out-param slot`);
+            const out = buf ?? new PtrArrayBuffer(size);
+            doEncode(new DataView(out), 0, fields, v);
+            return out;
+        }),
+        offsetOf: (name) => {
+            for (const f of fields)
+                if (f.name === name)
+                    return f.offset;
+            throw new Error(`ffi-struct: no field "${name}"`);
+        },
+    };
+}
+/** 平铺字段表 → '#' 声明：'#'/`#pack` 由构造器写入（顶层 kind 由函数名表明，字段表本身
+ *  不收指令键）。member 里混进的 '#' 前缀键在此剔除 —— 类型层已禁（fresh literal excess
+ *  check），这里运行时兜底，避免用户键覆盖构造器写入的 '#'/`#pack`。 */
+function buildDecl(kind, member, pack) {
+    const decl = { '#': kind };
+    if (pack !== undefined)
+        decl['#pack'] = pack;
+    for (const [k, v] of Object.entries(member))
+        if (!k.startsWith('#'))
+            decl[k] = v;
+    return decl;
+}
+export function struct(a, b, c) {
+    const isNamed = typeof a === 'string';
+    const raw = (isNamed ? b : a);
+    const opts = (isNamed ? c : b);
+    return createStruct(buildDecl('struct', raw, opts?.pack));
+}
+export function union(a, b, c) {
+    const isNamed = typeof a === 'string';
+    const raw = (isNamed ? b : a);
+    const opts = (isNamed ? c : b);
+    return createStruct(buildDecl('union', raw, opts?.pack));
+}