PyPTO 向量编程范式 mask_reg 掩码寄存器详解256 bit 粒度映射与元素级有效性控制【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto导读vf.mask_reg是 PyPTO 向量编程Vector FunctionVF范式中的元素级有效性控制容器它以固定 256 bit 的位宽配合可配置的 dtype 粒度决定 VF 算子中哪些元素真正参与运算。本文基于 mask_reg.md 主体文档结合仓库中 create_mask / update_mask 配套接口文档 与 VF API 源码实现系统讲解掩码的位宽粒度映射表、编译器自动声明机制、MaskReg 寄存器复用策略及完整可运行的调用示例帮助你正确使用掩码完成全量运算、尾块处理、条件选择与交替筛选等典型场景。一、功能说明mask_reg 是什么掩码寄存器mask_reg是 VF 计算中控制元素级有效性的专用容器用于控制 VF 算子中哪些元素参与运算。其设计要点如下固定位宽mask_reg 总位宽固定为256 bit与数据类型无关。粒度可配掩码粒度由关联的 dtype 参数决定即每多少 bit 对应一个数据元素。逐元素生效VF 算子执行时根据 mask_reg 中每个数据元素对应的比特位决定该元素是否参与运算比特位为 1有效该元素参与运算结果写入目的寄存器对应位置比特位为 0无效该元素不参与运算目的寄存器对应位置置零vf.full等少数算子支持通过 mode 参数选择保留原值参见 vf.create_mask 中的说明。这一机制使开发者无需修改数据本身仅通过掩码即可灵活控制一段寄存器数据中“哪些 lane 生效、哪些 lane 被屏蔽”是 VF 范式实现条件运算、尾块tail处理和模式化筛选的基础设施。二、产品支持情况产品形态支持情况Ascend 950PR / Ascend 950DT支持Atlas A3 训练系列产品 / Atlas A3 推理系列产品不支持Atlas A2 训练系列产品 / Atlas A2 推理系列产品不支持使用前请确认目标硬件属于 Ascend 950 系列A2/A3 系列产品上该接口不可用。三、原型定义mask_reg(dtype: DType) - mask_reg入参dtype掩码粒度对应的数据类型。返回值mask_reg类型。需要特别强调的是vf.mask_reg不能直接调用它由编译器在赋值形式中自动声明。也就是说mask_reg 对象通常不是通过显式构造产生的而是在preg vf.create_mask(...)、preg vf.eq(...)这类赋值语句中由编译器隐式创建。这也是本接口与普通 VF 算子最显著的差异详见下文“参数说明”与“约束说明”。四、参数说明参数输入/输出说明dtype输入掩码粒度对应的数据类型决定每多少 bit 对应一个数据元素。mask_reg 总位宽固定为 256 bit。-vf.mask_reg不能直接调用由编译器在赋值形式中自动声明。- mask_reg 在pypto_pro.language.vector_function函数内创建和使用函数结束后自动释放。- mask_reg 的 dtype 一般与配套的vf.reg_tensor的 dtype 一致不一致的情况下需要自行判断结果行为。- MaskReg 寄存器数量上限为 16。编译器会自动复用生命周期结束的寄存器和预留内存若寄存器与预留内存均存在可用空间将优先复用寄存器。其中“编译器自动复用”是 VF 范式资源管理的关键策略MaskReg 数量存在硬性上限16 个编译器通过分析寄存器生命周期将已结束使用的寄存器回收给后续掩码使用并在寄存器不足时回退到预留内存从而在有限硬件资源下支持任意数量的掩码逻辑。五、约束说明5.1 数据类型约束位宽粒度映射dtype 决定的是掩码粒度每多少 bit 对应一个数据元素而非 mask_reg 本身的类型——mask_reg 类型始终不变。完整的映射关系如下dtype元素位宽元素个数每元素掩码位数总掩码位数DT_INT8 / DT_UINT8 / DT_FP8E4M3FN / DT_FP8E5M2 / DT_FP8E8M0 / DT_HF8 / DT_FP4E2M1 / DT_FP4E1M28 bit2561 bitb8 粒度256 bitDT_FP16 / DT_UINT16 / DT_BF1616 bit1282 bitb16 粒度256 bitDT_FP32 / DT_INT32 / DT_UINT3232 bit644 bitb32 粒度256 bitDT_INT64 / DT_UINT6464 bit328 bitb64 粒度256 bit理解要点元素位宽越小单个 256 bit 掩码寄存器能覆盖的元素越多b8 粒度覆盖 256 个元素每元素 1 bitb64 粒度仅覆盖 32 个元素每元素 8 bit。FP8FP8E4M3FN/FP8E5M2/FP8E8M0/HF8与 FP4FP4E2M1/FP4E1M2均为 b8 存储按 b8 粒度处理这在 vf.update_mask 的约束说明中有同样明确的提示。源码层面VF API 实现 对create_mask的 dtype 处理也印证了这一映射所有 b8/b4 类型统一按 b8 掩码宽度处理INT64/UINT64 按 b64 掩码宽度处理内部使用pset_b32 punpack以匹配每元素 2 bit 的粒度。5.2 声明与生命周期约束vf.mask_reg不能直接调用由编译器在赋值形式中自动声明典型形式如preg vf.create_mask(...)或preg vf.eq(...)。mask_reg 在pypto_pro.language.vector_function函数内创建和使用函数结束后自动释放。MaskReg 数量上限为 16编译器自动复用生命周期结束的寄存器与预留内存并优先复用寄存器。六、返回值说明返回mask_reg类型即一个可用于后续 VF 算子如vf.add、vf.store_align谓词参数的掩码寄存器对象。七、调用示例以下示例来自 mask_reg.md 的官方调用示例展示了“创建全量掩码 → 加载 Tile 数据 → 带掩码做加法”的完整流程import pypto_pro.language as pl pl.vector_function def vf_kernel(): preg vf.create_mask(patternpl.MaskPattern.ALL, dtypepl.DT_FP32) reg vf.load_align(src_tile, 0) reg_out vf.add(reg, reg, preg)其中vf.create_mask(patternpl.MaskPattern.ALL, dtypepl.DT_FP32)创建全有效的 FP32 粒度掩码默认 pattern 即为 ALL故也可省略 pattern 参数vf.load_align(src_tile, 0)从源 Tile 对齐加载寄存器数据vf.add(reg, reg, preg)将加法结果写回reg_out所有 lane 在 ALL 掩码下均参与运算。若希望对比“有效/无效”两种行为的差异可将掩码换成pl.MaskPattern.ALLF全 0此时所有元素被屏蔽目的寄存器对应位置被置零可直观验证掩码对结果的屏蔽效果。八、纵深扩展mask_reg 的创建、更新与典型用法mask_reg 本身由编译器自动声明开发者实际接触的入口是 vf.create_mask 与 vf.update_mask 两个配套接口它们在源码中与 mask_reg 文档同属一个功能族见 VF API 源码 中create_mask/update_mask的接口定义。8.1 vf.create_mask按模式创建掩码函数原型create_mask(pattern: Optional[MaskPattern] None, dtype: Optional[DType] None) - pregpattern掩码模式决定 mask_reg 中哪些元素被置为有效1、哪些置为无效0对应pypto_pro.language.MaskPattern枚举默认MaskPattern.ALLdtype掩码对应的数据类型决定掩码粒度默认DT_FP32即 b32 粒度64 元素 × 4 bit。MaskPattern 的完整模式表以 DT_FP32 / 64 元素为例取值含义示意64 元素MaskPattern.ALL所有元素有效全 1MaskPattern.ALLF所有元素无效全 0MaskPattern.VL1最低 1 个元素有效1000...0000MaskPattern.VL2最低 2 个元素有效1100...0000MaskPattern.VL4最低 4 个元素有效1111...0000MaskPattern.VL8最低 8 个元素有效前 8 个 1其余 0MaskPattern.VL16最低 16 个元素有效前 16 个 1其余 0MaskPattern.VL32最低 32 个元素有效前 32 个 1其余 0MaskPattern.VL64最低 64 个元素有效前 64 个 1其余 0MaskPattern.VL128最低 128 个元素有效全部有效仅 8/16 位宽粒度下有意义MaskPattern.H最低一半元素有效前 32 个 1后 32 个 0MaskPattern.Q最低四分之一元素有效前 16 个 1后 48 个 0MaskPattern.M33 的倍数位置有效每第 3 个元素为 1MaskPattern.M44 的倍数位置有效每第 4 个元素为 18.2 vf.update_mask从标量值更新掩码函数原型update_mask(scalar, dtype: Optional[DType] None) - pregscalar标量值其比特位直接定义新的掩码模式dtype可选决定掩码宽度默认DT_FP32b32 粒度。该接口以寄存器为操作数、不涉及地址对齐也不修改全局寄存器的值。典型用法见 update_mask.md 调用示例通过vf.update_mask(0xFFFFFFFF, dtypepl.DT_FP16)按 b16 粒度生成全有效掩码配合vf.load_align与vf.store_align完成带掩码的搬运。8.3 典型使用场景综合 create_mask.md 的功能说明mask_reg 的典型应用包括全量运算patternALL所有元素参与运算是最常用形态尾块处理当数据长度不是寄存器宽度的整数倍时用VL1 ~ VL128限制最后一块的参与元素数避免越界或多余计算条件选择通过vf.eq、vf.gt等比较算子生成掩码再用vf.select按掩码从两个寄存器中选取元素源码 VF API 中比较类算子均返回 MaskReg 型谓词掩码交替处理用H、Q、M3、M4等模式对寄存器中的部分元素进行筛选运算。8.4 类型转换astype中的掩码行为不同数据类型对应的掩码位宽不一致在astype类型转换时mask_reg 会根据输入的源操作数进行有效元素筛选。例如 16 位宽与 32 位宽之间互转时掩码粒度会随源数据类型的位宽变化而重新解释因此混用不同 dtype 的掩码时需自行确认结果行为文档明确提示mask_reg 的 dtype 一般应与配套vf.reg_tensor一致不一致时需自行判断。九、从源码看实现与验证接口定义create_mask/update_mask均以_api_decl静态方法形式定义在 VF API 的Vf类中docstring 明确了默认值pattern 默认 ALL、dtype 默认 FP32以及 b8/b4 统一按 b8 宽度、INT64/UINT64 按 b64 宽度处理的实现细节。枚举导出MaskPattern、MaskWidth等枚举类型通过 python/pypto_pro/language/init.py 从内部模块导入并公开因此代码中可直接以pl.MaskPattern.ALL、pl.DT_FP32形式使用。测试佐证仓库 python/tests/ut/pypto_pro/language/parser/test_vf_scope.py 与 python/tests/st/pypto_pro/frontend/vf_api/test_vf_basic_ops.py 等用例覆盖了掩码相关的解析与端到端行为其中 test_vf_scope.py 专门验证掩码在 vector_function 作用域内的创建与使用规则。十、使用注意事项小结不要显式调用vf.mask_reg掩码寄存器必须通过preg vf.create_mask(...)、preg vf.eq(...)等赋值形式由编译器自动声明dtype 决定粒度而非类型掩码粒度随 dtype 变化b8/b16/b32/b64mask_reg 类型始终不变FP8/FP4 统一按 b8 粒度处理注意数量上限MaskReg 上限 16 个编译器自动复用生命周期结束的寄存器与预留内存优先复用寄存器生命周期掩码仅在pypto_pro.language.vector_function函数内有效函数结束后自动释放无效元素的结果掩码位为 0 时目的寄存器对应位置默认置零vf.full等少数算子支持通过 mode 参数选择保留原值硬件前提该功能仅 Ascend 950PR/950DT 支持A2/A3 系列产品不支持。【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PyPTO 向量编程范式 mask_reg 掩码寄存器详解：256 bit 粒度映射与元素级有效性控制
PyPTO 向量编程范式 mask_reg 掩码寄存器详解256 bit 粒度映射与元素级有效性控制【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto导读vf.mask_reg是 PyPTO 向量编程Vector FunctionVF范式中的元素级有效性控制容器它以固定 256 bit 的位宽配合可配置的 dtype 粒度决定 VF 算子中哪些元素真正参与运算。本文基于 mask_reg.md 主体文档结合仓库中 create_mask / update_mask 配套接口文档 与 VF API 源码实现系统讲解掩码的位宽粒度映射表、编译器自动声明机制、MaskReg 寄存器复用策略及完整可运行的调用示例帮助你正确使用掩码完成全量运算、尾块处理、条件选择与交替筛选等典型场景。一、功能说明mask_reg 是什么掩码寄存器mask_reg是 VF 计算中控制元素级有效性的专用容器用于控制 VF 算子中哪些元素参与运算。其设计要点如下固定位宽mask_reg 总位宽固定为256 bit与数据类型无关。粒度可配掩码粒度由关联的 dtype 参数决定即每多少 bit 对应一个数据元素。逐元素生效VF 算子执行时根据 mask_reg 中每个数据元素对应的比特位决定该元素是否参与运算比特位为 1有效该元素参与运算结果写入目的寄存器对应位置比特位为 0无效该元素不参与运算目的寄存器对应位置置零vf.full等少数算子支持通过 mode 参数选择保留原值参见 vf.create_mask 中的说明。这一机制使开发者无需修改数据本身仅通过掩码即可灵活控制一段寄存器数据中“哪些 lane 生效、哪些 lane 被屏蔽”是 VF 范式实现条件运算、尾块tail处理和模式化筛选的基础设施。二、产品支持情况产品形态支持情况Ascend 950PR / Ascend 950DT支持Atlas A3 训练系列产品 / Atlas A3 推理系列产品不支持Atlas A2 训练系列产品 / Atlas A2 推理系列产品不支持使用前请确认目标硬件属于 Ascend 950 系列A2/A3 系列产品上该接口不可用。三、原型定义mask_reg(dtype: DType) - mask_reg入参dtype掩码粒度对应的数据类型。返回值mask_reg类型。需要特别强调的是vf.mask_reg不能直接调用它由编译器在赋值形式中自动声明。也就是说mask_reg 对象通常不是通过显式构造产生的而是在preg vf.create_mask(...)、preg vf.eq(...)这类赋值语句中由编译器隐式创建。这也是本接口与普通 VF 算子最显著的差异详见下文“参数说明”与“约束说明”。四、参数说明参数输入/输出说明dtype输入掩码粒度对应的数据类型决定每多少 bit 对应一个数据元素。mask_reg 总位宽固定为 256 bit。-vf.mask_reg不能直接调用由编译器在赋值形式中自动声明。- mask_reg 在pypto_pro.language.vector_function函数内创建和使用函数结束后自动释放。- mask_reg 的 dtype 一般与配套的vf.reg_tensor的 dtype 一致不一致的情况下需要自行判断结果行为。- MaskReg 寄存器数量上限为 16。编译器会自动复用生命周期结束的寄存器和预留内存若寄存器与预留内存均存在可用空间将优先复用寄存器。其中“编译器自动复用”是 VF 范式资源管理的关键策略MaskReg 数量存在硬性上限16 个编译器通过分析寄存器生命周期将已结束使用的寄存器回收给后续掩码使用并在寄存器不足时回退到预留内存从而在有限硬件资源下支持任意数量的掩码逻辑。五、约束说明5.1 数据类型约束位宽粒度映射dtype 决定的是掩码粒度每多少 bit 对应一个数据元素而非 mask_reg 本身的类型——mask_reg 类型始终不变。完整的映射关系如下dtype元素位宽元素个数每元素掩码位数总掩码位数DT_INT8 / DT_UINT8 / DT_FP8E4M3FN / DT_FP8E5M2 / DT_FP8E8M0 / DT_HF8 / DT_FP4E2M1 / DT_FP4E1M28 bit2561 bitb8 粒度256 bitDT_FP16 / DT_UINT16 / DT_BF1616 bit1282 bitb16 粒度256 bitDT_FP32 / DT_INT32 / DT_UINT3232 bit644 bitb32 粒度256 bitDT_INT64 / DT_UINT6464 bit328 bitb64 粒度256 bit理解要点元素位宽越小单个 256 bit 掩码寄存器能覆盖的元素越多b8 粒度覆盖 256 个元素每元素 1 bitb64 粒度仅覆盖 32 个元素每元素 8 bit。FP8FP8E4M3FN/FP8E5M2/FP8E8M0/HF8与 FP4FP4E2M1/FP4E1M2均为 b8 存储按 b8 粒度处理这在 vf.update_mask 的约束说明中有同样明确的提示。源码层面VF API 实现 对create_mask的 dtype 处理也印证了这一映射所有 b8/b4 类型统一按 b8 掩码宽度处理INT64/UINT64 按 b64 掩码宽度处理内部使用pset_b32 punpack以匹配每元素 2 bit 的粒度。5.2 声明与生命周期约束vf.mask_reg不能直接调用由编译器在赋值形式中自动声明典型形式如preg vf.create_mask(...)或preg vf.eq(...)。mask_reg 在pypto_pro.language.vector_function函数内创建和使用函数结束后自动释放。MaskReg 数量上限为 16编译器自动复用生命周期结束的寄存器与预留内存并优先复用寄存器。六、返回值说明返回mask_reg类型即一个可用于后续 VF 算子如vf.add、vf.store_align谓词参数的掩码寄存器对象。七、调用示例以下示例来自 mask_reg.md 的官方调用示例展示了“创建全量掩码 → 加载 Tile 数据 → 带掩码做加法”的完整流程import pypto_pro.language as pl pl.vector_function def vf_kernel(): preg vf.create_mask(patternpl.MaskPattern.ALL, dtypepl.DT_FP32) reg vf.load_align(src_tile, 0) reg_out vf.add(reg, reg, preg)其中vf.create_mask(patternpl.MaskPattern.ALL, dtypepl.DT_FP32)创建全有效的 FP32 粒度掩码默认 pattern 即为 ALL故也可省略 pattern 参数vf.load_align(src_tile, 0)从源 Tile 对齐加载寄存器数据vf.add(reg, reg, preg)将加法结果写回reg_out所有 lane 在 ALL 掩码下均参与运算。若希望对比“有效/无效”两种行为的差异可将掩码换成pl.MaskPattern.ALLF全 0此时所有元素被屏蔽目的寄存器对应位置被置零可直观验证掩码对结果的屏蔽效果。八、纵深扩展mask_reg 的创建、更新与典型用法mask_reg 本身由编译器自动声明开发者实际接触的入口是 vf.create_mask 与 vf.update_mask 两个配套接口它们在源码中与 mask_reg 文档同属一个功能族见 VF API 源码 中create_mask/update_mask的接口定义。8.1 vf.create_mask按模式创建掩码函数原型create_mask(pattern: Optional[MaskPattern] None, dtype: Optional[DType] None) - pregpattern掩码模式决定 mask_reg 中哪些元素被置为有效1、哪些置为无效0对应pypto_pro.language.MaskPattern枚举默认MaskPattern.ALLdtype掩码对应的数据类型决定掩码粒度默认DT_FP32即 b32 粒度64 元素 × 4 bit。MaskPattern 的完整模式表以 DT_FP32 / 64 元素为例取值含义示意64 元素MaskPattern.ALL所有元素有效全 1MaskPattern.ALLF所有元素无效全 0MaskPattern.VL1最低 1 个元素有效1000...0000MaskPattern.VL2最低 2 个元素有效1100...0000MaskPattern.VL4最低 4 个元素有效1111...0000MaskPattern.VL8最低 8 个元素有效前 8 个 1其余 0MaskPattern.VL16最低 16 个元素有效前 16 个 1其余 0MaskPattern.VL32最低 32 个元素有效前 32 个 1其余 0MaskPattern.VL64最低 64 个元素有效前 64 个 1其余 0MaskPattern.VL128最低 128 个元素有效全部有效仅 8/16 位宽粒度下有意义MaskPattern.H最低一半元素有效前 32 个 1后 32 个 0MaskPattern.Q最低四分之一元素有效前 16 个 1后 48 个 0MaskPattern.M33 的倍数位置有效每第 3 个元素为 1MaskPattern.M44 的倍数位置有效每第 4 个元素为 18.2 vf.update_mask从标量值更新掩码函数原型update_mask(scalar, dtype: Optional[DType] None) - pregscalar标量值其比特位直接定义新的掩码模式dtype可选决定掩码宽度默认DT_FP32b32 粒度。该接口以寄存器为操作数、不涉及地址对齐也不修改全局寄存器的值。典型用法见 update_mask.md 调用示例通过vf.update_mask(0xFFFFFFFF, dtypepl.DT_FP16)按 b16 粒度生成全有效掩码配合vf.load_align与vf.store_align完成带掩码的搬运。8.3 典型使用场景综合 create_mask.md 的功能说明mask_reg 的典型应用包括全量运算patternALL所有元素参与运算是最常用形态尾块处理当数据长度不是寄存器宽度的整数倍时用VL1 ~ VL128限制最后一块的参与元素数避免越界或多余计算条件选择通过vf.eq、vf.gt等比较算子生成掩码再用vf.select按掩码从两个寄存器中选取元素源码 VF API 中比较类算子均返回 MaskReg 型谓词掩码交替处理用H、Q、M3、M4等模式对寄存器中的部分元素进行筛选运算。8.4 类型转换astype中的掩码行为不同数据类型对应的掩码位宽不一致在astype类型转换时mask_reg 会根据输入的源操作数进行有效元素筛选。例如 16 位宽与 32 位宽之间互转时掩码粒度会随源数据类型的位宽变化而重新解释因此混用不同 dtype 的掩码时需自行确认结果行为文档明确提示mask_reg 的 dtype 一般应与配套vf.reg_tensor一致不一致时需自行判断。九、从源码看实现与验证接口定义create_mask/update_mask均以_api_decl静态方法形式定义在 VF API 的Vf类中docstring 明确了默认值pattern 默认 ALL、dtype 默认 FP32以及 b8/b4 统一按 b8 宽度、INT64/UINT64 按 b64 宽度处理的实现细节。枚举导出MaskPattern、MaskWidth等枚举类型通过 python/pypto_pro/language/init.py 从内部模块导入并公开因此代码中可直接以pl.MaskPattern.ALL、pl.DT_FP32形式使用。测试佐证仓库 python/tests/ut/pypto_pro/language/parser/test_vf_scope.py 与 python/tests/st/pypto_pro/frontend/vf_api/test_vf_basic_ops.py 等用例覆盖了掩码相关的解析与端到端行为其中 test_vf_scope.py 专门验证掩码在 vector_function 作用域内的创建与使用规则。十、使用注意事项小结不要显式调用vf.mask_reg掩码寄存器必须通过preg vf.create_mask(...)、preg vf.eq(...)等赋值形式由编译器自动声明dtype 决定粒度而非类型掩码粒度随 dtype 变化b8/b16/b32/b64mask_reg 类型始终不变FP8/FP4 统一按 b8 粒度处理注意数量上限MaskReg 上限 16 个编译器自动复用生命周期结束的寄存器与预留内存优先复用寄存器生命周期掩码仅在pypto_pro.language.vector_function函数内有效函数结束后自动释放无效元素的结果掩码位为 0 时目的寄存器对应位置默认置零vf.full等少数算子支持通过 mode 参数选择保留原值硬件前提该功能仅 Ascend 950PR/950DT 支持A2/A3 系列产品不支持。【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考