描述

本次提交补齐 Roll 算子的开源实现，面向 Atlas A2 训练系列产品提供 ACLNN 两阶段调用接口。

Roll 的目标是沿指定维度对输入张量执行循环位移；当 dims 为空时，语义等价于先对输入做逻辑展平，再执行一维 roll，最后恢复原始形状。

本次实现重点解决以下问题：

1. 正式支持范围内的语义对齐。
2. 单维、多维、最后一维、非最后一维等不同访存形态下的统一实现。
3. 在控制实现复杂度的前提下，保证正式支持范围内的性能收益。

当前版本支持范围如下：

• 数据类型：uint8、int8、bfloat16、float16、float32、int32、uint32
• 数据格式：ND
• 维度范围：0-D 到 8-D
• 语义特性：负维度归一化、重复维度合并、dims 为空的 flatten roll

当前版本不支持：

• bool
• int64
• 非 ND 格式

实现上采用 Host 侧归一化与 Tiling、Kernel 侧多路径搬运的方案：

flowchart TD
    A[ACLNN 接口] --> B[参数校验]
    B --> C[dims shifts 归一化]
    C --> D[重复维度合并]
    D --> E[生成 Tiling 信息]
    E --> F[Kernel 路径选择]
    F --> G[连续段 Copy]
    F --> H[按行 Roll]
    F --> I[按 Block Roll]
    F --> J[Segmented Fallback]

整体设计思路如下：

1. Host 侧负责参数校验、负维归一化、重复维度合并和切分信息生成。
2. dims 为空时退化为 flatten roll，避免继续走原始多维索引路径。
3. 单 active dim 与多 active dim 分开建模，分别提取更适合搬运的结构信息。
4. 最后一维滚动优先按行处理，非最后维滚动优先按 block 重排。
5. 保留 segmented fallback 作为通用正确性兜底路径。

Kernel 路径选择可概括为：

flowchart TD
    A[Kernel Process] --> B{activeDimCount == 0?}
    B -->|Yes| C[Identity Copy]
    B -->|No| D{dimNum == 1?}
    D -->|Yes| E[Flatten Roll]
    D -->|No| F{single active dim?}
    F -->|Yes| G{activeDim == 0?}
    G -->|Yes| H[Leading Dim Roll]
    G -->|No| I{innerSize == 1 and last dim?}
    I -->|Yes| J[Last Dim Row Roll]
    I -->|No| K[Single Dim Block Roll]
    F -->|No| L{last active dim is final dim?}
    L -->|Yes| M[Multi-Dim Last-Dim Roll]
    L -->|No| N[Multi-Dim Non-Last Roll]
    N --> O[Segmented Fallback]

本次实现保留的优化主线不是单点 shape 特化，而是以下几类可复用策略：

1. 连续段优先
   能转为连续段搬运的场景，优先使用连续 copy 或源端对齐 copy，减少逐元素处理。

2. 最后一维按行优化
   围绕最后一维滚动构建按行搬运、按行拼接和行组处理路径，降低访存碎片。

3. 非最后维按 block 重排
   对中间维或多维组合滚动，优先按 block 建模，减少重复索引计算。

4. 小宽度定向增强
   对部分 BF16、小宽度最后维和部分 uint8 小块场景，调整切分与 patch 策略，但不引入写死单一 shape 的独立实现。

输入约束方面，当前版本要求：

1. 输入输出 dtype 一致。
2. 输入输出 shape 一致。
3. rank 不超过 8。
4. dims 为空时，shifts 长度必须为 1。
5. dims 非空时，shifts 与 dims 长度必须一致。
6. dims 的取值范围为 [-rank, rank)。
7. 0 维输入时，shifts 长度必须为 1，且 dims 为空。

关联的Issue

• https://gitcode.com/cann/ops-math/issues/1971

测试

本次改动包含以下验证范围：

1. ACLNN 接口参数校验用例
2. Host 侧 InferShape / Tiling 用例
3. Kernel 路径基础功能用例
4. dims 为空、负维度、重复维度合并等关键语义场景
5. 正式支持 dtype 范围内的基础调用样例

验收目标包括：

1. 正式支持范围内功能结果正确。
2. 单维、多维、负维和重复维度归并场景行为正确。
3. 正式支持范围内的性能目标优于参考 TBE。

文档更新

本次同步补充了算子说明文档、接口文档以及需求与设计说明。

类型标签

• Bug修复
• 新特性
• 性能优化
• 文档更新
• 其他，请描述：新增 Roll 算子实现与配套文档