Table of Contents

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_ 仍可用)

★ 历史勘误:BinaryLayoutAttribute XML 注释曾表述"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-matrix workflow × {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)。