CANN pyasc 算子编程GlobalTensor.set_global_buffer 全局内存绑定原理与实战【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyascGlobalTensor 是 CANN pyascPython 算子编程接口中表示 Global Memory全局内存/外部存储数据的核心类型。set_global_buffer负责把 Host 侧传入的全局数据地址绑定到 GlobalTensor 上是几乎每个算子 kernel 的开场动作。本文以该 API 为线索结合仓库源码tensor.py、Tensor.td、test_global_tensor.py 与 examples/01_add讲解它的签名语义、参数约定、底层 IR 实现与典型实战用法帮助你写对每一个从全局内存出发的算子。一、GlobalTensor 与全局内存在昇腾 AI Core 的编程模型中数据存放在两类存储上Global Memory全局内存GMAI Core 外部的片外存储容量大、带宽相对有限对应代码中的GlobalTensorLocal Memory本地内存LMAI Core 内部存储按逻辑位置划分为 VECIN、VECOUT、VECCALC、A1、A2、B1、B2、CO1、CO2 等对应代码中的LocalTensor。pyasc 中GlobalTensor类的定位在源码注释中写得很清楚GlobalTensor 用来存放 Global Memory外部存储的全局数据python/asc/language/core/tensor.py。一个典型的 kernel 流程是先用set_global_buffer把 Host 传入的全局地址绑定到 GlobalTensor再用data_copy等指令把数据搬运到 LocalTensor 参与计算最后把结果写回全局内存。set_global_buffer就是这条链路的起点——它是 GlobalTensor 生命周期中第一个、也是最重要的初始化动作。二、函数签名与语义asc.language.core.GlobalTensor.set_global_buffer提供两个重载见原 API 文档 asc.language.core.GlobalTensor.set_global_buffer.mdGlobalTensor.set_global_buffer(buffer: GlobalAddress | None None) - None GlobalTensor.set_global_buffer(buffer: GlobalAddress | None None, buffer_size: int | None None) - None其语义为传入全局数据地址初始化 GlobalTensor。两种重载的区别仅在于是否显式指定buffer_size只传buffer仅完成地址绑定不携带长度信息同时传buffer与buffer_size在绑定的同时声明该 GlobalTensor 所包含的元素个数供依赖长度信息的指令使用。从源码看这两个重载在 python/asc/language/core/tensor.py 中通过overload声明实际实现是同一个函数体overload def set_global_buffer(self, buffer: Optional[GlobalAddress] None) - None: ... overload def set_global_buffer(self, buffer: Optional[GlobalAddress] None, buffer_size: Optional[int] None) - None: ... require_jit set_tensor_docstring(tensor_nameGlobalTensor, api_nameset_global_buffer) def set_global_buffer(self, buffer: Optional[GlobalAddress] None, buffer_size: Optional[RuntimeInt] None) - None: if buffer is None or buffer.dtype is None: raise ValueError(Either DataType or typed GlobalAddress must be provided to instantiate GlobalTensor) dtype buffer.dtype super().__init__(dtype) builder global_builder.get_ir_builder() ir_type ir.get_global_tensor_type(dtype.to_ir()) handle builder.create_asc_GlobalTensorOp(ir_type) self.dtype dtype self.handle handle if buffer_size is not None: builder.create_asc_GlobalTensorSetGlobalBufferOp(self.to_ir(), buffer.to_ir(), _mat(buffer_size).to_ir()) else: builder.create_asc_GlobalTensorSetGlobalBufferOp(self.to_ir(), buffer.to_ir())实现要点可从源码结构确认校验buffer为None或缺少dtype时抛出ValueError提示必须提供带数据类型的GlobalAddress类型推导GlobalTensor 的元素类型直接取自buffer.dtype因此传入的GlobalAddress必须携带正确的数据类型信息IR 构造先创建asc_GlobalTensorOp得到全局张量句柄再按是否传buffer_size分别生成带/不带 size 参数的asc_GlobalTensorSetGlobalBufferOprequire_jit该 API 只能在 JIT 编译的 kernel 上下文中调用对应 pyasc 的asc.jit编程模型。三、参数详解buffer全局数据指针类型GlobalAddress | None即 Host 侧传入的全局数据指针元素类型为 PrimTypepyasc 中的DataType。说明GlobalAddress是 pyasc 对全局地址的抽象定义在 python/asc/language/core/ir_value.py。它支持__add__指针偏移运算内部生成arith.IndexCast与emitasc.ptr_offset操作因此可以写出x_gm.set_global_buffer(x offset, length)这种按核/按块切分全局内存的惯用法见下文实战示例。注意在set_global_buffer的实现中若传入的地址缺少dtype信息会直接抛异常调用前应确保地址是带类型的GlobalAddress如从 kernel 参数传入的asc.GlobalAddress。buffer_size数据个数类型int | None可选。含义GlobalTensor 所包含的、类型为 PrimType 的数据个数注意是元素个数不是字节数。约束需自行保证不会超出实际数据的长度即buffer_size不得超过 Host 侧为该地址分配的实际元素数量。这是开发者需要负责的边界约定框架不做越界校验。可选性省略buffer_size时GlobalTensor 仍可正常绑定地址但依赖长度信息的操作如data_copy的搬运长度、get_size返回的元素数等需要由调用方另行保证。四、与 Ascend C 的对应关系set_global_buffer与 Ascend C 的GlobalTensor::SetGlobalBuffer一一对应。原 API 文档给出两个 C 原型__aicore__ inline void SetGlobalBuffer(__gm__ PrimType* buffer, uint64_t bufferSize) __aicore__ inline void SetGlobalBuffer(__gm__ PrimType* buffer)在 pyasc 的 MLIR 方言层这一对应关系被定义在 TableGen 文件中include/ascir/Dialect/Asc/IR/Core/Tensor.tddef AscendC_GlobalTensorSetGlobalBufferOp : APIOpglobal_tensor.set_global_buffer, SetGlobalBuffer, [AscMemberFunc] { let summary Set data buffer of global tensor; let arguments (ins AscendC_GlobalTensor:$tensor, AnyRankedOrUnrankedMemRef:$buffer, OptionalAnyInteger:$size); ... }从该定义可以确认三点实现事实操作名global_tensor.set_global_buffer直接映射到 Ascend C 的SetGlobalBuffer成员函数buffer参数在 IR 中建模为AnyRankedOrUnrankedMemRef即任意秩的 memref 全局地址size为OptionalAnyInteger印证了buffer_size可选这一 API 设计。整个链路为Python 层set_global_buffer→ pyasc IR 的asc_GlobalTensorSetGlobalBufferOp→ MLIR 方言层global_tensor.set_global_bufferOp → Ascend C 代码生成SetGlobalBuffer。五、典型实战用法5.1 最小示例来自原 API 文档data_size 256 input_global asc.GlobalTensor() input_global.set_global_buffer(src_gm, data_size) input_local in_queue_x.alloc_tensor(asc.int32) asc.data_copy(input_local, input_global, data_size)该示例展示的标准三步asc.GlobalTensor()创建空全局张量set_global_buffer(src_gm, data_size)把源地址src_gm绑定进来并声明长度为data_size个元素asc.data_copy(input_local, input_global, data_size)将其搬运到本地队列张量参与后续计算。5.2 多核分块buffer offset惯用法在真实的算子 kernel 中通常需要按核切分全局数据。仓库示例 examples/01_add/add.py 给出了完整范式asc.jit def vadd_kernel(x: asc.GlobalAddress, y: asc.GlobalAddress, z: asc.GlobalAddress, block_length: int): offset asc.get_block_idx() * block_length x_gm asc.GlobalTensor() y_gm asc.GlobalTensor() z_gm asc.GlobalTensor() x_gm.set_global_buffer(x offset, block_length) y_gm.set_global_buffer(y offset, block_length) z_gm.set_global_buffer(z offset, block_length) ...要点解析asc.get_block_idx()获取当前 AI Core 的块索引乘以block_length得到本核负责的数据偏移x offset利用GlobalAddress.__add__做指针偏移得到本核的起始地址每个 GlobalTensor 绑定各自核内的地址与长度实现多核并行下各核互不越界的全局内存视图后续配合x_gm[i * tile_length:]这类切片GlobalTensor 支持__getitem__子索引见 python/asc/language/core/tensor.py逐 tile 搬运计算。同样的用法还出现在 examples/03_matmul_mix/matmul_mix.py、examples/07_swiglu/swiglu.py 等示例中是 pyasc 算子开发的通用模式。六、与其他 GlobalTensor 接口的联动set_global_buffer完成初始化后GlobalTensor 的其他成员方法才有意义各接口文档见 docs/python-api/language/core.md 及其 generated 目录接口作用依赖关系get_phy_addr([offset])获取全局物理地址依赖已绑定 bufferget_size()返回元素个数有 shape 时返回 shape 乘积否则由 IR 查询依赖绑定时的长度信息get_value(offset)按偏移读取单个元素依赖已绑定 bufferset_value(offset, value)按偏移写入单个元素依赖已绑定 bufferset_l2_cache_hint(mode, rw_mode)设置 L2 Cache 命中模式依赖已绑定 bufferset_shape_info(shape_info)设置形状信息依赖已绑定 buffer从实现上看get_size在无 shape 时会生成asc_GlobalTensorGetSizeOp由 IR 层面查询这也说明在编译期声明buffer_size有助于编译器推导出更准确的长度信息。七、测试验证仓库单元测试 python/test/unit/language/core/test_global_tensor.py 直接覆盖了该接口的两种调用形态def test_set_global_buffer(mock_launcher_run): asc.jit def kernel_set_global_buffer(x: asc.GlobalAddress) - None: x_gm asc.GlobalTensor() x_gm.set_global_buffer(x) x_gm.set_global_buffer(x, 8192) data MockTensor(asc.float32) kernel_set_global_buffer1 assert mock_launcher_run.call_count 1该测试验证了不传buffer_size与传buffer_size如 8192两种重载均可在 JIT kernel 内正常编译运行。同文件中的test_get_phy_addr、test_get_size、test_get_value、test_operator、test_set_l2_cache_hint、test_set_shape_info等用例都遵循先set_global_buffer再调用其他方法的结构进一步印证它是 GlobalTensor 一切操作的初始化前提。八、注意事项与最佳实践先绑定、后使用GlobalTensor 的读写、搬运、查址接口全部依赖set_global_buffer完成初始化忘记调用会在后续指令生成或运行时暴露问题类型一致性buffer必须携带正确的DataTypeGlobalTensor 的元素类型由它推导类型不一致会导致后续指令语义错误长度边界自担buffer_size声明的是元素个数且需自行保证不会超出实际数据的长度这是开发者需要严格遵守的内存安全约定框架不负责越界检查多核场景善用指针偏移结合asc.get_block_idx()与GlobalAddress.__add__做核级分块是 pyasc 标准的多核数据处理模式可参考 examples/01_add/add.py 等示例无长度绑定的场景如果后续操作不依赖长度信息可以省略buffer_size但建议在需要data_copy、get_size等长度相关操作时显式传入帮助编译期推导JIT 上下文限制该 API 带require_jit标记只能在asc.jit装饰的 kernel 函数中调用不能在普通 Python 代码中直接使用。掌握set_global_buffer就等于掌握了 pyasc 算子从全局内存出发的第一步——正确绑定地址与长度后续的搬运、计算、写回流程才能在此基础上可靠展开。【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CANN pyasc 算子编程：GlobalTensor.set_global_buffer 全局内存绑定原理与实战
CANN pyasc 算子编程GlobalTensor.set_global_buffer 全局内存绑定原理与实战【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyascGlobalTensor 是 CANN pyascPython 算子编程接口中表示 Global Memory全局内存/外部存储数据的核心类型。set_global_buffer负责把 Host 侧传入的全局数据地址绑定到 GlobalTensor 上是几乎每个算子 kernel 的开场动作。本文以该 API 为线索结合仓库源码tensor.py、Tensor.td、test_global_tensor.py 与 examples/01_add讲解它的签名语义、参数约定、底层 IR 实现与典型实战用法帮助你写对每一个从全局内存出发的算子。一、GlobalTensor 与全局内存在昇腾 AI Core 的编程模型中数据存放在两类存储上Global Memory全局内存GMAI Core 外部的片外存储容量大、带宽相对有限对应代码中的GlobalTensorLocal Memory本地内存LMAI Core 内部存储按逻辑位置划分为 VECIN、VECOUT、VECCALC、A1、A2、B1、B2、CO1、CO2 等对应代码中的LocalTensor。pyasc 中GlobalTensor类的定位在源码注释中写得很清楚GlobalTensor 用来存放 Global Memory外部存储的全局数据python/asc/language/core/tensor.py。一个典型的 kernel 流程是先用set_global_buffer把 Host 传入的全局地址绑定到 GlobalTensor再用data_copy等指令把数据搬运到 LocalTensor 参与计算最后把结果写回全局内存。set_global_buffer就是这条链路的起点——它是 GlobalTensor 生命周期中第一个、也是最重要的初始化动作。二、函数签名与语义asc.language.core.GlobalTensor.set_global_buffer提供两个重载见原 API 文档 asc.language.core.GlobalTensor.set_global_buffer.mdGlobalTensor.set_global_buffer(buffer: GlobalAddress | None None) - None GlobalTensor.set_global_buffer(buffer: GlobalAddress | None None, buffer_size: int | None None) - None其语义为传入全局数据地址初始化 GlobalTensor。两种重载的区别仅在于是否显式指定buffer_size只传buffer仅完成地址绑定不携带长度信息同时传buffer与buffer_size在绑定的同时声明该 GlobalTensor 所包含的元素个数供依赖长度信息的指令使用。从源码看这两个重载在 python/asc/language/core/tensor.py 中通过overload声明实际实现是同一个函数体overload def set_global_buffer(self, buffer: Optional[GlobalAddress] None) - None: ... overload def set_global_buffer(self, buffer: Optional[GlobalAddress] None, buffer_size: Optional[int] None) - None: ... require_jit set_tensor_docstring(tensor_nameGlobalTensor, api_nameset_global_buffer) def set_global_buffer(self, buffer: Optional[GlobalAddress] None, buffer_size: Optional[RuntimeInt] None) - None: if buffer is None or buffer.dtype is None: raise ValueError(Either DataType or typed GlobalAddress must be provided to instantiate GlobalTensor) dtype buffer.dtype super().__init__(dtype) builder global_builder.get_ir_builder() ir_type ir.get_global_tensor_type(dtype.to_ir()) handle builder.create_asc_GlobalTensorOp(ir_type) self.dtype dtype self.handle handle if buffer_size is not None: builder.create_asc_GlobalTensorSetGlobalBufferOp(self.to_ir(), buffer.to_ir(), _mat(buffer_size).to_ir()) else: builder.create_asc_GlobalTensorSetGlobalBufferOp(self.to_ir(), buffer.to_ir())实现要点可从源码结构确认校验buffer为None或缺少dtype时抛出ValueError提示必须提供带数据类型的GlobalAddress类型推导GlobalTensor 的元素类型直接取自buffer.dtype因此传入的GlobalAddress必须携带正确的数据类型信息IR 构造先创建asc_GlobalTensorOp得到全局张量句柄再按是否传buffer_size分别生成带/不带 size 参数的asc_GlobalTensorSetGlobalBufferOprequire_jit该 API 只能在 JIT 编译的 kernel 上下文中调用对应 pyasc 的asc.jit编程模型。三、参数详解buffer全局数据指针类型GlobalAddress | None即 Host 侧传入的全局数据指针元素类型为 PrimTypepyasc 中的DataType。说明GlobalAddress是 pyasc 对全局地址的抽象定义在 python/asc/language/core/ir_value.py。它支持__add__指针偏移运算内部生成arith.IndexCast与emitasc.ptr_offset操作因此可以写出x_gm.set_global_buffer(x offset, length)这种按核/按块切分全局内存的惯用法见下文实战示例。注意在set_global_buffer的实现中若传入的地址缺少dtype信息会直接抛异常调用前应确保地址是带类型的GlobalAddress如从 kernel 参数传入的asc.GlobalAddress。buffer_size数据个数类型int | None可选。含义GlobalTensor 所包含的、类型为 PrimType 的数据个数注意是元素个数不是字节数。约束需自行保证不会超出实际数据的长度即buffer_size不得超过 Host 侧为该地址分配的实际元素数量。这是开发者需要负责的边界约定框架不做越界校验。可选性省略buffer_size时GlobalTensor 仍可正常绑定地址但依赖长度信息的操作如data_copy的搬运长度、get_size返回的元素数等需要由调用方另行保证。四、与 Ascend C 的对应关系set_global_buffer与 Ascend C 的GlobalTensor::SetGlobalBuffer一一对应。原 API 文档给出两个 C 原型__aicore__ inline void SetGlobalBuffer(__gm__ PrimType* buffer, uint64_t bufferSize) __aicore__ inline void SetGlobalBuffer(__gm__ PrimType* buffer)在 pyasc 的 MLIR 方言层这一对应关系被定义在 TableGen 文件中include/ascir/Dialect/Asc/IR/Core/Tensor.tddef AscendC_GlobalTensorSetGlobalBufferOp : APIOpglobal_tensor.set_global_buffer, SetGlobalBuffer, [AscMemberFunc] { let summary Set data buffer of global tensor; let arguments (ins AscendC_GlobalTensor:$tensor, AnyRankedOrUnrankedMemRef:$buffer, OptionalAnyInteger:$size); ... }从该定义可以确认三点实现事实操作名global_tensor.set_global_buffer直接映射到 Ascend C 的SetGlobalBuffer成员函数buffer参数在 IR 中建模为AnyRankedOrUnrankedMemRef即任意秩的 memref 全局地址size为OptionalAnyInteger印证了buffer_size可选这一 API 设计。整个链路为Python 层set_global_buffer→ pyasc IR 的asc_GlobalTensorSetGlobalBufferOp→ MLIR 方言层global_tensor.set_global_bufferOp → Ascend C 代码生成SetGlobalBuffer。五、典型实战用法5.1 最小示例来自原 API 文档data_size 256 input_global asc.GlobalTensor() input_global.set_global_buffer(src_gm, data_size) input_local in_queue_x.alloc_tensor(asc.int32) asc.data_copy(input_local, input_global, data_size)该示例展示的标准三步asc.GlobalTensor()创建空全局张量set_global_buffer(src_gm, data_size)把源地址src_gm绑定进来并声明长度为data_size个元素asc.data_copy(input_local, input_global, data_size)将其搬运到本地队列张量参与后续计算。5.2 多核分块buffer offset惯用法在真实的算子 kernel 中通常需要按核切分全局数据。仓库示例 examples/01_add/add.py 给出了完整范式asc.jit def vadd_kernel(x: asc.GlobalAddress, y: asc.GlobalAddress, z: asc.GlobalAddress, block_length: int): offset asc.get_block_idx() * block_length x_gm asc.GlobalTensor() y_gm asc.GlobalTensor() z_gm asc.GlobalTensor() x_gm.set_global_buffer(x offset, block_length) y_gm.set_global_buffer(y offset, block_length) z_gm.set_global_buffer(z offset, block_length) ...要点解析asc.get_block_idx()获取当前 AI Core 的块索引乘以block_length得到本核负责的数据偏移x offset利用GlobalAddress.__add__做指针偏移得到本核的起始地址每个 GlobalTensor 绑定各自核内的地址与长度实现多核并行下各核互不越界的全局内存视图后续配合x_gm[i * tile_length:]这类切片GlobalTensor 支持__getitem__子索引见 python/asc/language/core/tensor.py逐 tile 搬运计算。同样的用法还出现在 examples/03_matmul_mix/matmul_mix.py、examples/07_swiglu/swiglu.py 等示例中是 pyasc 算子开发的通用模式。六、与其他 GlobalTensor 接口的联动set_global_buffer完成初始化后GlobalTensor 的其他成员方法才有意义各接口文档见 docs/python-api/language/core.md 及其 generated 目录接口作用依赖关系get_phy_addr([offset])获取全局物理地址依赖已绑定 bufferget_size()返回元素个数有 shape 时返回 shape 乘积否则由 IR 查询依赖绑定时的长度信息get_value(offset)按偏移读取单个元素依赖已绑定 bufferset_value(offset, value)按偏移写入单个元素依赖已绑定 bufferset_l2_cache_hint(mode, rw_mode)设置 L2 Cache 命中模式依赖已绑定 bufferset_shape_info(shape_info)设置形状信息依赖已绑定 buffer从实现上看get_size在无 shape 时会生成asc_GlobalTensorGetSizeOp由 IR 层面查询这也说明在编译期声明buffer_size有助于编译器推导出更准确的长度信息。七、测试验证仓库单元测试 python/test/unit/language/core/test_global_tensor.py 直接覆盖了该接口的两种调用形态def test_set_global_buffer(mock_launcher_run): asc.jit def kernel_set_global_buffer(x: asc.GlobalAddress) - None: x_gm asc.GlobalTensor() x_gm.set_global_buffer(x) x_gm.set_global_buffer(x, 8192) data MockTensor(asc.float32) kernel_set_global_buffer1 assert mock_launcher_run.call_count 1该测试验证了不传buffer_size与传buffer_size如 8192两种重载均可在 JIT kernel 内正常编译运行。同文件中的test_get_phy_addr、test_get_size、test_get_value、test_operator、test_set_l2_cache_hint、test_set_shape_info等用例都遵循先set_global_buffer再调用其他方法的结构进一步印证它是 GlobalTensor 一切操作的初始化前提。八、注意事项与最佳实践先绑定、后使用GlobalTensor 的读写、搬运、查址接口全部依赖set_global_buffer完成初始化忘记调用会在后续指令生成或运行时暴露问题类型一致性buffer必须携带正确的DataTypeGlobalTensor 的元素类型由它推导类型不一致会导致后续指令语义错误长度边界自担buffer_size声明的是元素个数且需自行保证不会超出实际数据的长度这是开发者需要严格遵守的内存安全约定框架不负责越界检查多核场景善用指针偏移结合asc.get_block_idx()与GlobalAddress.__add__做核级分块是 pyasc 标准的多核数据处理模式可参考 examples/01_add/add.py 等示例无长度绑定的场景如果后续操作不依赖长度信息可以省略buffer_size但建议在需要data_copy、get_size等长度相关操作时显式传入帮助编译期推导JIT 上下文限制该 API 带require_jit标记只能在asc.jit装饰的 kernel 函数中调用不能在普通 Python 代码中直接使用。掌握set_global_buffer就等于掌握了 pyasc 算子从全局内存出发的第一步——正确绑定地址与长度后续的搬运、计算、写回流程才能在此基础上可靠展开。【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考