Skip to content

docs(runtime): add L3/L2 multichannel MPMC design#755

Open
PKUZHOU wants to merge 1 commit into
hw-native-sys:mainfrom
PKUZHOU:docs/l3-l2-multichannel-mpmc-upstream
Open

docs(runtime): add L3/L2 multichannel MPMC design#755
PKUZHOU wants to merge 1 commit into
hw-native-sys:mainfrom
PKUZHOU:docs/l3-l2-multichannel-mpmc-upstream

Conversation

@PKUZHOU
Copy link
Copy Markdown
Contributor

@PKUZHOU PKUZHOU commented May 12, 2026

Summary

  • add a design doc for L3 host CPU to L2 NPU send/recv semantics
  • describe multi-lane SPSC channels that expose MPMC semantics
  • outline ABI, memory layout, consistency rules, implementation phases, and tests

Tests

  • not run; documentation-only change

Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a design document for a multi-channel MPMC communication interface between the L3 host CPU and L2 NPU runtime, utilizing a multi-lane SPSC architecture to ensure memory consistency without cross-device CAS. The review feedback highlights critical inconsistencies in the proposed memory layouts: specifically, a calculation error in the padding for HostDeviceChannelHeader and a size discrepancy in HostDeviceDesc where the actual struct size exceeds the stated 64-byte target, potentially leading to alignment issues.

uint64_t payload_base;
uint64_t payload_bytes;
uint64_t fatal_status;
uint8_t reserved[64 - 48];
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

HostDeviceChannelHeader 结构体的大小计算不一致。根据字段定义:

  • magiclane_depth 共 6 个 uint32_t,占 24 字节。
  • control_bytesfatal_status 共 4 个 uint64_t,占 32 字节。

当前已定义字段总计 56 字节。若要实现 64 字节对齐,reserved 数组的大小应为 64 - 56 = 8 字节。当前定义的 64 - 48 会使结构体总大小变为 72 字节,破坏了对齐预期。

Suggested change
uint8_t reserved[64 - 48];
uint8_t reserved[64 - 56];
References
  1. Ensure documentation and diagrams accurately reflect implementation details regarding resource lifecycles, especially when persistence is used to maintain internal state like caches.

};
```

`HostDeviceDesc` 的 slot 大小固定为 64B,保证 producer 可以先写完整 descriptor,
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

此处提到 HostDeviceDesc 的 slot 大小固定为 64B,但上文结构体定义(第 161-171 行)的实际大小为 72 字节:

  • 元数据字段(opcoderoute)总计 40 字节。
  • inline_data[32] 占 32 字节。

由于结构体使用了 alignas(64),编译器会将其大小向上补齐至 128 字节,这与“固定为 64B”的描述矛盾。如果必须支持 32 字节的 inline_data(如第 295 行所述),建议缩减元数据字段(例如将 seqcorrelation_id 改为 uint32_t)以凑齐 64 字节;或者将 inline_data 缩减为 24 字节并同步更新相关文档。

References
  1. Ensure documentation and diagrams accurately reflect implementation details regarding resource lifecycles, especially when persistence is used to maintain internal state like caches.

@PKUZHOU PKUZHOU force-pushed the docs/l3-l2-multichannel-mpmc-upstream branch from 99dbd51 to dc8c799 Compare May 12, 2026 08:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant