Skip to content

数据面与 Operation 标识

FRAME_SUBMIT 创建一个 operation。Operation 标识与 frame 标识相互关联,但不能混为一谈:

  • operation_id: u64 是稳定的生命周期标识,供取消、调度、进度、部分结果、路由提示、对象引用、 trace 关联与丢弃原因使用。
  • header.frame_id: u32 是有序的数据面工作单元标识,供 submit、终结结果、重放与 frame-oriented profile 数据关联使用。

实现必须在 operation 的完整生命周期内保存这一对标识。禁止从本地 handle 推导 operation_id,禁止把它 截断为 frame_id,也禁止静默令两者相等。SDK/FFI 的 opaque handle 只在进程内有效,永远不是 wire identity。

FRAME_SUBMIT Metadata

Preview4 将 fixed metadata 冻结为 72 字节:

Offset字段类型规则
0src_widthu16Tensor 字段;非 tensor payload 必须为零。
2src_heightu16Tensor 字段;非 tensor payload 必须为零。
4tile_widthu16Tensor 字段。
6tile_heightu16Tensor 字段。
8tile_countu16Tensor 字段。
10section_countu16声明的 tensor section 数。
12frame_classu8Profile 定义的 frame class。
13input_profileu8标准 input profile 注册值。
14tile_index_modeu8Tile index 编码。
15reserved0u8必须为零。
16latency_budget_msu16Submit latency budget。
18target_fps_x100u16可选 frame-rate target。
20retry_of_frameu32旧 frame identity;无则为零。
24tile_base_idu32首个 tile identity。
28camera_bytesu32Camera block 声明长度。
32tile_index_bytesu32Tile-index block 声明长度。
36reserved1u32必须为零。
40operation_idu64本次 submit 的非零生命周期标识。
48reserved2u32必须为零。
52submit_modeu8inlinereferencemixed
53budget_policyu8已冻结的 budget-policy bitmask。
54loss_tolerance_policyu8Frame policy,或以 0xff 表示继承。
55reserved3u8必须为零。
56object_ref_masku32标准 referenced-object slots。
60dependency_frame_idu32依赖 frame;无则为零。
64payload_kind_bitmapu32声明的 payload families。
68payload_frame_countu16Typed payload frame 数。
70reserved4u16必须为零。

tile_index_bytes 固定占用 32..3536..39 是 reserved,不得与 tile-index 长度重叠。 operation_id 固定占用 40..47,每个合法的 Preview4 FRAME_SUBMIT 都必须携带它。

Body Region 长度规则

当前 NNRP/1 body prelude 继承 32 字节字段布局,但使用当前 descriptor 尺寸:

  1. object_reference_bytes 必须是 24 字节 object-reference block 的整数倍。
  2. typed_payload_descriptor_bytes 必须是当前 24 字节 typed payload descriptor 的整数倍; 对 FRAME_SUBMITRESULT_PUSH,它必须等于 payload_frame_count * 24
  3. extension_descriptor_bytes 必须是 16 字节 extension descriptor 的整数倍。

Preview2 的 16 字节 typed-payload descriptor 仅是历史布局,当前 Preview4 wire format 不接受它。

RESULT_PUSH 结果类别与复用

RESULT_PUSH.result_class 描述本次交付的主体类别,result_flags 描述可以叠加的属性。因此 partial 结果可以同时复用旧 frame,但必须同时满足以下约束:

  1. result_class=stale_reuse 或设置 result_flags.stale 时,reused_frame_id 必须非零。
  2. 未声明 stale 语义时,reused_frame_id 必须为零。
  3. 对 tensor payload,result_class=partial 或设置 result_flags.partial 时, dropped_tile_count 必须非零,且 covered_tile_count + dropped_tile_count == tile_count。 非 tensor payload 必须清零 tensor coverage 字段,并通过 typed-payload descriptor 与 profile-specific metadata 表达 partial 范围。
  4. Partial 与 stale 可以组合;组合结果使用 result_class=partial、同时设置 partial | stale flags,并携带非零 reused_frame_id

运行时关联

  1. Client 在编码 submit 前分配两个标识。
  2. Server 接受 submit 时记录两个标识,并将它们绑定到本地 operation handle。
  3. Partial result 与 operation-scope control frame 在 fixed metadata 中使用 operation_id
  4. 每个 operation-scope 消息必须在 header.frame_id 中携带其 metadata operation_id 已绑定的 frame 标识;接收端必须拒绝未知 operation 或不匹配的标识对。
  5. RESULT_PUSHRESULT_DROP 继续使用 header.frame_id 关联。
  6. 只有对应 terminal event 已交付或持久记录后,才释放 operation 生命周期状态。
  7. TRACE_CONTEXT 是固定 metadata 不重复携带 operation_id 的例外。 header.frame_id=0 表示 session scope;非零值必须等于 active operation 记录的 submit frame ID,并通过保留的 operation 配对解析回对应 operation。

NNRP Documentation