Tensor
产 品 支 持 情 况
| 产 品 | 是 否 支 持 |
|---|---|
| Ascend 950PR/Ascend 950DT | √ |
功 能 说 明
需 要 包 含 的 头 文 件 为：#include "tensor_api/tensor.h"。
Tensor用 于 将 内 存 访 问 引 擎Engine与 布 局Layout绑 定 起 来。Engine描 述 物 理 存 储 位 置 和 访 问 方 式，Layout描 述 数 据 的 形 状 和 布 局。Tensor分 为GlobalTensor和LocalTensor两 种，其 中GlobalTensor用 来 存 放Global Memory（外 部 存 储）的 全 局 数 据，LocalTensor用 于 存 放AI Core中Local Memory（内 部 存 储）的 数 据。二 者 的 公 共 接 口 由BaseTensor<TensorAttribute<EngineType, LayoutType>>提 供。
原 型 定 义
template <typename EngineType, typename LayoutType>
struct TensorAttribute {};
template <typename T>
struct BaseTensor {};
template <typename EngineType, typename LayoutType>
struct BaseTensor<TensorAttribute<EngineType, LayoutType>> {
using iterator = typename EngineType::iterator;
using valueType = typename EngineType::valueType;
using elementType = typename EngineType::elementType;
using reference = typename EngineType::reference;
using engineType = EngineType;
using layoutType = LayoutType;
static constexpr int rank = LayoutType::rank;
__aicore__ inline BaseTensor();
__aicore__ inline BaseTensor(const EngineType& engine, const LayoutType& layout);
__aicore__ inline constexpr decltype(auto) Tensor() const;
__aicore__ inline constexpr decltype(auto) Engine() const;
__aicore__ inline constexpr decltype(auto) Engine();
__aicore__ inline constexpr decltype(auto) Layout() const;
__aicore__ inline constexpr decltype(auto) Data() const;
__aicore__ inline constexpr decltype(auto) Data();
__aicore__ inline constexpr decltype(auto) Shape() const;
__aicore__ inline constexpr decltype(auto) Stride() const;
__aicore__ inline constexpr auto Size() const;
__aicore__ inline constexpr auto Capacity() const;
template <typename Coord>
__aicore__ inline constexpr decltype(auto) operator[](const Coord& coord);
template <typename Coord>
__aicore__ inline constexpr decltype(auto) operator[](const Coord& coord) const;
template <typename Coord>
__aicore__ inline constexpr decltype(auto) operator()(const Coord& coord);
template <typename Coord>
__aicore__ inline constexpr decltype(auto) operator()(const Coord& coord) const;
template <typename Coord0, typename Coord1, typename... Coords>
__aicore__ inline constexpr decltype(auto) operator()(const Coord0& c0, const Coord1& c1, const Coords&... cs);
template <typename Coord0, typename Coord1, typename... Coords>
__aicore__ inline constexpr decltype(auto) operator()(const Coord0& c0, const Coord1& c1, const Coords&... cs) const;
template <typename Coord, typename Info>
__aicore__ inline constexpr decltype(auto) Slice(const Coord& coord, const Info& info);
template <typename Coord, typename Info>
__aicore__ inline constexpr decltype(auto) Slice(const Coord& coord, const Info& info) const;
};
template <typename EngineType, typename LayoutType>
struct GlobalTensor<TensorAttribute<EngineType, LayoutType>>
: public BaseTensor<TensorAttribute<EngineType, LayoutType>> {
__aicore__ inline GlobalTensor() = default;
__aicore__ inline constexpr void SetL2CacheHint(Te::CacheMode mode);
};
template <typename EngineType, typename LayoutType>
struct LocalTensor<TensorAttribute<EngineType, LayoutType>>
: public BaseTensor<TensorAttribute<EngineType, LayoutType>> {
__aicore__ inline LocalTensor() = default;
};
参 数 说 明
模 板 参 数 说 明
| 参 数 名 | 类 型 | 描 述 |
|---|---|---|
| EngineType | 输 入 | 张 量 的 内 存 访 问 引 擎 类 型。 |
| LayoutType | 输 入 | 张 量 的 布 局 类 型，用 于 描 述Shape和Stride。 |
| T | 输 入 | 泛 型 模 板 参 数，用 于 基 础 模 板 或 特 化 匹 配。 |
返 回 值 说 明
Tensor相 关 类 型 本 身 为 类 型 定 义，不 直 接 返 回 值。
通 过MakeTensor（...）构 造 张 量 时：若 存 放Global Memory（外 部 存 储）的 全 局 数 据，则 返 回GlobalTensor，存 放AI Core中Local Memory（内 部 存 储）的 数 据 返 回LocalTensor。
成 员 函 数
Tensor()
功 能 说 明
获 取 张 量 对 象 自 身。
函 数 原 型
C++__aicore__ inline constexpr decltype(auto) Tensor() const返 回 值 说 明
返 回 当 前Tensor对 象 的 常 量 引 用。
Engine()
功 能 说 明
获 取 张 量 绑 定 的Engine对 象。
函 数 原 型
C++__aicore__ inline constexpr decltype(auto) Engine() const __aicore__ inline constexpr decltype(auto) Engine()返 回 值 说 明
返 回Engine对 象 的（常 量）引 用。
Layout()
功 能 说 明
获 取 张 量 绑 定 的Layout对 象。
函 数 原 型
C++__aicore__ inline constexpr decltype(auto) Layout() const返 回 值 说 明
返 回Layout对 象 的 常 量 引 用。
Data()
功 能 说 明
获 取 底 层 数 据 起 始 迭 代 器。
函 数 原 型
C++__aicore__ inline constexpr decltype(auto) Data() const __aicore__ inline constexpr decltype(auto) Data()返 回 值 说 明
返 回
Engine().Begin()的 结 果，即 数 据 起 始 迭 代 器 的（常 量）引 用 或 值。
Shape()
功 能 说 明
获 取 张 量 对 应 的Shape信 息。
函 数 原 型
C++__aicore__ inline constexpr decltype(auto) Shape() const返 回 值 说 明
返 回Layout中 的Shape对 象。
Stride()
功 能 说 明
获 取 张 量 对 应 的Stride信 息。
函 数 原 型
C++__aicore__ inline constexpr decltype(auto) Stride() const返 回 值 说 明
返 回Layout中 的Stride对 象。
Size()
功 能 说 明
获 取 张 量 覆 盖 的 逻 辑 元 素 总 数。
函 数 原 型
C++__aicore__ inline constexpr auto Size() const返 回 值 说 明
返 回
Layout().Size()的 计 算 结 果。
Capacity()
功 能 说 明
获 取 张 量 在 当 前 布 局 下 占 用 的 实 际 容 量。
函 数 原 型
C++__aicore__ inline constexpr auto Capacity() const返 回 值 说 明
返 回
Layout().Capacity()的 计 算 结 果。
operator[]
功 能 说 明
按 多 维 坐 标 访 问 单 个 元 素。
函 数 原 型
C++template <typename Coord> __aicore__ inline constexpr decltype(auto) operator[](const Coord& coord) template <typename Coord> __aicore__ inline constexpr decltype(auto) operator[](const Coord& coord) const参 数 说 明
参 数 名 输 入/输 出 描 述 coord 输 入 多 维 逻 辑 坐 标。 约 束 说 明 仅__gm__, __ubuf__地 址 空 间 支 持 使 用 该 接 口，AICore上 的 地 址 空 间（ca，cb，cc，cbuf）不 具 备 标 量 直 接 访 问 能 力。
返 回 值 说 明
返 回Data()[Layout()(coord)]对 应 的 元 素 引 用。
operator()
功 能 说 明
以 给 定 坐 标 为 起 点，返 回 一 个 从 当 前 位 置 开 始 的 子 张 量。
函 数 原 型
C++template <typename Coord> __aicore__ inline constexpr decltype(auto) operator()(const Coord& coord) template <typename Coord> __aicore__ inline constexpr decltype(auto) operator()(const Coord& coord) const template <typename Coord0, typename Coord1, typename... Coords> __aicore__ inline constexpr decltype(auto) operator()(const Coord0& c0, const Coord1& c1, const Coords&... cs) template <typename Coord0, typename Coord1, typename... Coords> __aicore__ inline constexpr decltype(auto) operator()(const Coord0& c0, const Coord1& c1, const Coords&... cs) const参 数 说 明
参 数 名 输 入/输 出 描 述 coord 输 入 起 始 坐 标 元 组。 c0, c1, cs... 输 入 多 个 坐 标 参 数，会 被 包 装 为MakeCoord(c0, c1, cs...)。 返 回 值 说 明
返 回 从 指 定 坐 标 位 置 开 始 的 子 张 量 对 象。
Slice()
功 能 说 明
从 指 定 坐 标 处 切 出 一 个 带 新 布 局 信 息 的 子 张 量。
函 数 原 型
C++template <typename Coord, typename Info> __aicore__ inline constexpr decltype(auto) Slice(const Coord& coord, const Info& info) template <typename Coord, typename Info> __aicore__ inline constexpr decltype(auto) Slice(const Coord& coord, const Info& info) const参 数 说 明
参 数 名 输 入/输 出 描 述 coord 输 入 切 片 起 始 坐 标。 info 输 入 切 片 描 述 信 息，可 以 为Shape或Layout。 返 回 值 说 明
返 回 切 片 后 的 子 张 量 对 象。新 张 量 的Engine指 向 切 片 起 始 位 置，Layout由
MakeSliceLayout(coord, Layout(), info)生 成。
SetL2CacheHint()
功 能 说 明
设 置GlobalTensor访 问GM时 的L2 Cache Hint。
函 数 原 型
C++__aicore__ inline constexpr void SetL2CacheHint(Te::CacheMode mode)参 数 说 明
参 数 名 输 入/输 出 描 述 mode 输 入 L2缓 存 模 式。 返 回 值 说 明
无 返 回 值。
约 束 说 明
该 接 口 仅 存 在 于GlobalTensor中，LocalTensor不 提 供 此 接 口。
调 用 示 例
using namespace AscendC::Te;
// 示 例1：构 造 一 个GM张 量
auto gmLayout = MakeLayout(MakeShape(128, 128), MakeStride(128, 1));
auto gmTensor = MakeTensor(MakeMemPtr<Location::GM, float>(gmAddr), gmLayout);
auto gmShape = gmTensor.Shape(); // (128, 128)
auto gmStride = gmTensor.Stride(); // (128, 1)
auto gmSize = gmTensor.Size(); // 16384
auto gmCap = gmTensor.Capacity(); // 16384
gmTensor.SetL2CacheHint(CacheMode::CACHE_MODE_NORMAL);
// 示 例2：按 坐 标 访 问 元 素
auto coord = MakeCoord(5, 10);
auto value = gmTensor[coord];
// 示 例3：获 取 子 张 量
auto subTensor = gmTensor(MakeCoord(16, 16));
// 示 例4：按Shape切 片
auto sliceTensor = gmTensor.Slice(MakeCoord(0, 0), MakeShape(32, 32));
// 示 例5：构 造 一 个LocalTensor
auto localLayout = MakeFrameLayout<NZLayoutPtn, LayoutTraitDefault<float>>(32, 32);
auto localTensor = MakeTensor(MakeMemPtr<Location::L1, float>(l1Addr), localLayout);
auto localData = localTensor.Data();