BinaryLayout 字节序与对齐规格
validation-program-design §4(批 5)验收件——
[BinaryLayout]生成 codec 的字节面契约在此定死。 结论性表述("跨平台逐字节一致")以本页 + 黄金快照三平台矩阵(§5)为准;主张三律适用。
§1 范围:字节面契约,不含内存面
规格对象是生成 codec({Type}Codec)读写 Span<byte>/ReadOnlySpan<byte> 的字节面行为。
struct 的内存面(sizeof、数组 stride、GC 布局)不在契约内——它由运行时/平台决定,
任何依赖内存面推断 wire 行为的用法都违反本规格(唯一合法通道 = codec API)。
§2 字节序语义
§2.1 声明点:per-type 单一声明
- 端序在
[BinaryLayout(Endianness = ...)]struct 级声明,一处声明管辖该类型全部多字节字段。 - 缺省
LayoutEndianness.LittleEndian(家族既有铁律,unified-binary-layout.md §1.2); 网络字节序协议(DNS 等)显式声明BigEndian。 - 没有其他端序控制点——不存在字段级端序、全局端序开关或运行期切换。
§2.2 实现关系:显式转换收口,与 host 字节序解耦
生成物对多字节字段的全部读写走 System.Buffers.Binary.BinaryPrimitives.Read/Write{Primitive}{LittleEndian|BigEndian}:
- 从不 host 原生直写(无
MemoryMarshal/ 无指针转型 / 无BitConvertor隐式端序)—— 编码产物与运行 host 的字节序完全解耦。 byte字段与 byte 底层 enum 无端序问题(dest[offset] = value直存直取)。- 由此得出本规格的核心可测主张:同一份源码在任意 host 字节序的平台上产物逐字节一致 (x86/ARM 小端、大端页面对齐差异均不进入产物)。断言手段 = §5 黄金快照三平台矩阵。
字段支持集(KLSG003 卡口):uint/ushort/ulong/long/int/short/byte/float/double/bool 十基元
- 同底层类型 enum + 嵌套
[BinaryLayout]struct(批 A① 扩展——bool独立 emit 形态:读source[offset] != 0、写0/1整字节;浮点按 IEEE 754 原生形态)。sbyte不在支持集 (不支持的类型宁可报错也不静默降级)。
§2.2.1 位域(单字节 v1——批 C1)
[LayoutBitField(bit, width = 1)] 与 [FieldOffset] 同字段叠加——bit = 字节内起始位
(0-7,LSB-first:bit0 = 字节最低位,方向定死入档),width = 位宽。语义与执法:
| 面 | 形态 |
|---|---|
| 载体 | bool(width 恒 1)/ byte / byte 底层枚举——超集 KLSG009 |
| 越界 | bit+width ≤ 8(跨字节位域端序歧义 v1 不做)、width ≥ 1、bool width 恒 1——KLSG010 |
| 能力位 | 位域字段禁叠加 [OrFlags]/[IsEmpty](整字段语义正交禁混)——KLSG011 |
| 重叠 | 同字节位域按位区间判交(不相交 = 合法共存);位域与同字节普通字段恒冲突——KLSG006 位粒度 |
| 读 | bool:(source[o] >> bit & 1) != 0;位段:(cast)(byte)((source[o] >> bit) & lowMask) |
| 写 | RMW 掩码合并:dest[o] = (byte)((dest[o] & ~mask) \| (值表达式 & mask))——只触碰声明位,未声明位保持原值 |
| 端序 | 单字节无端序问题(§2.2 byte 同律) |
| 常量 | FieldConstants 开启时位域字段附 Bit_X/Width_X(位定位事实显式化) |
§2.3 嵌套:端序按类型独立,不传播
嵌套字段的编解码完全委托给嵌套类型自己的 codec({Nested}Codec.Read/Write)。
外层的 Endianness 不传播给嵌套类型——混合端序流(如外层 BE 头 + 内嵌 LE 体)是合法形态:
GBMixedOuter(BE 声明,22B)
├─ Inner : GBInnerLE(LE 声明,16B) → 按 LE 编解码
├─ Mode : GBWide → 按 BE(外层声明)
└─ Tag : ushort → 按 BE
该语义被运行时黄金快照逐字节锁定(GBMixedOuter.hex:前 16B 小端、后 6B 大端)。
声明嵌套时必须逐类型核对端序声明——这是本规格唯一的"隐式"风险点,靠 §5 黄金而非约定防守。
§2.4 readonly struct 的整体 Read 三分支
readonly 字段只能构造函数赋值,整体 Read 按三分支生成(全部 BinaryPrimitives,无 MemoryMarshal):
| 形态 | 整体 Read |
|---|---|
| 非 readonly | object initializer(字段可写) |
| readonly + 最大构造函数参数类型序列 == 字段类型序列 | 构造调用 new T(字段按 offset 序) |
| readonly + 无法构造覆盖全部字段 | 不生成整体 Read(逐字段 Read_ 仍可用) |
★ 历史勘误:
BinaryLayoutAttributeXML 注释曾表述"readonly struct 用MemoryMarshal.Read整体反序列化"——实现早已演进为上表三分支(BinaryPrimitives 收口),注释已随本规格修正。MemoryMarshal路径才会引入 host 字节序依赖,三分支形态下它不存在。
WireMessage 线格式的 LE 单一裁定与报文布局见 Wire 面《WireMessage 线格式规格》 (
src/KernLab.Loom.Wire/docs/wire-format-spec.md)。
§3 对齐 / Pack 裁定
- 契约入口:
[StructLayout(LayoutKind.Explicit, Size = N)]+ 逐字段[FieldOffset(o)]—— 两个显式量(每字段偏移、总长)是全部布局事实。Size与字段 extent 交叉校验(KLSG001), 字段重叠禁断(KLSG006),缺Size报错(KLSG005)。 - 运行期零对齐依赖:codec 访问全部是
span.Slice(offset, size)+BinaryPrimitives—— 非对齐偏移(如偏移 3 的 uint)合法且安全,产物不受字段自然对齐影响。 - Pack 不参与契约:
LayoutKind.Explicit下字段偏移由[FieldOffset]唯一决定,Pack不改变 codec 行为;Pack影响的 struct 整体对齐/sizeof/数组 stride 属于 §1 排除的内存面。 - 裁定:禁止把隐式对齐当作行为依赖。跨平台行为漂移的经典来源(Sequential/Auto 布局的
平台相关填充)在声明入口处即被排除——
[BinaryLayout]只收 Explicit 形态。
§4 校验与辅助生成面(字节面相关的语义锁定)
| API | 语义 |
|---|---|
Write(dest, in value, validate = false) |
容量守卫(dest.Length < StructSize → ArgumentException);validate: true 时 ValidEquals/ValidHasFlags 字段替换为合法常量写入(脏值不出现在字节面),ValidRange/ValidNonDefault 只参与 Validate 判定不参与替换 |
Read(source) |
容量守卫同上;还原逐字段值 |
Validate(in value) |
Valid* 特性逐条判定,全部通过返回 true |
OrFlags(dest, flags) |
原地 OR 目标字段,仅触碰该字段字节(黄金逐字节验证其余偏移不动) |
IsEmpty*(source) |
从字节面判空(目标字段 == 0),不构造 struct |
Create() |
有 ValidEquals 且非 readonly 时生成——合法默认实例 |
§5 黄金快照纪律(跨平台一致的断言手段)
双层 golden,互补不互替:
| 层 | 锁什么 | 位置 |
|---|---|---|
| 源码级 | 生成器发射文本(BinaryLayoutGoldenTests + GoldenTestBase) |
Golden/BinaryLayout/*.g.cs |
| 运行时字节流 | 真编译 fixtures → codec 产物逐字节(本批新增) | Golden/Bytes/*.hex(hex 文本入库) |
- 重新生成:
GOLDEN_DUMP=1跑测试。入库前必须人工验算关键段(golden 由测试同一构造逻辑 产出,盲目 dump 存在同漂风险——批 5 曾靠人工验算抓出混合端序 fixture 声明遗漏)。 - 三平台矩阵:
platform-matrixworkflow × {windows-latest(win-x64), ubuntu-latest(linux-x64), ubuntu-24.04-arm(linux-arm64)},net10.0 单腿(TFM 维度主线 CI 双腿已盖)。 §2.2 的实现形态使平台差异在原理上不可达,矩阵的作用是持续实证该主张而非发现差异。
§6 变长尾部长度契约(#137——读写两端的长度语义)
带 [LayoutTail] 的 struct(下记 head = [StructLayout].Size,即固定头字节数)生成三 API;无 tail 的 struct 不生成——StructSize 即总长,无契约缺口。
多尾段(#138):[LayoutTail] 可声明多条(如 Key+Value 双变长)——按声明序编号,每段 [Len 4B][载荷] 次第排布于固定头后;段 k 偏移 = head + Σ(4 + 前序段载荷长)。GetTotalSize 逐段走 len 链(任一段负 len/前缀越界 = -1);TryRead 全段校验(任一段截断 = false);Write 守卫覆盖全部段。CLR 内存面约束独立于线面:引用型尾字段的 [FieldOffset] 须 8 对齐互不重叠,且不超 [StructLayout].Size(KLSG012)——head 随之增大(padding 线面可见)。
| API | 形态 | 失败语义 |
|---|---|---|
GetTotalSize(ReadOnlySpan<byte> source) |
从尾部 len 前缀探测记录总长(head + 4 + len);只读 len 前缀、不要求载荷在场(分帧/预分配用途) | 缓冲不足 head+4 / 负 len / 总长超 int.MaxValue → -1(不抛) |
GetWriteSize(in T value) |
head + 4 + 尾载荷字节数(string 按 UTF8 字节数计)——精确预分配 | 不失败(值形态决定长度) |
TryRead(ReadOnlySpan<byte> source, out T value, out int bytesConsumed) |
防御式整体读;bytesConsumed = head + 4 + len(成功),失败 = 0 |
越界/负 len/截断 → false(不抛,Reject 契约) |
守卫硬化(同 PR):tail 结构的 Write 守卫从只查固定头改为覆盖 head + 4 + 载荷 全长(ArgumentException("Buffer too small…"));Read 对 len 前缀先读入局部并校验——负值/截断报 ArgumentException("尾部载荷长度非法…"),不再透出 Slice 的 ArgumentOutOfRangeException。
tail / 无 tail 两形态行为差异:
| 行为 | 无 tail | 有 tail |
|---|---|---|
| 记录总长 | StructSize(常量) |
运行期 = head + 4 + len(探测经 GetTotalSize) |
Write 守卫 |
dest.Length ≥ StructSize |
dest.Length ≥ head + 4 + 载荷(逐次求值) |
| 缓冲不足 | ArgumentException |
同左(含载荷区) |
| 恶意 len | 不适用 | Read 抛 ArgumentException;TryRead/GetTotalSize 返回 false/-1 |
readonly + 不可构造 |
不生成整体 Read |
同左——三 API 亦不生成(GetWriteSize 除外,随 Write 在场生成) |
§7 定长记录数组段(#136——[LayoutArray])
[LayoutArray(CountField = "Count")] 标注 T[] 字段(T = [BinaryLayout] 且含 StructSize 的 struct):head([StructLayout].Size)+ count×元素记录,count 落在声明的基元整型固定字段上(声明即契约)。数组段字段不参与固定布局/extent/overlap(同尾字段);线面排布于 head 之后。
生成游标 API(字段名 {F}):
| API | 语义 | 失败语义 |
|---|---|---|
{F}ElementSize 常量 |
元素 StructSize | — |
{F}ArraySize(int count) |
count×元素大小 | — |
Write{F}Array(Span<byte> dest, ReadOnlySpan<T> items) |
逐元素 ElemCodec.Write 端序收口 | dest.Length < items.Length×ElementSize → ArgumentException |
TryRead{F}Array(ReadOnlySpan<byte> source, int count, out T[] items) |
逐元素 ElemCodec.Read | count < 0 或 (long)count×ElementSize > source.Length → false(计数字段与实际元素数不一致的防御对称——Reject) |
声明非法(元素未标注 [BinaryLayout] 的同编译 struct / CountField 缺失或非固定整型)= KLSG013。消费编排:Read(head) → 取 count 字段 → TryRead{F}Array(buffer, count)。