数据格式
互推导关系
推导规则
当一个API（如aclnnAdd、aclnnMul等）输入的Tensor数据类型不一致时，API内部会推导出一个数据类型，将输入数据转换成该数据类型进行计算。
:::note 说明
- 为方便描述，表格中使用的数据类型是简写形式，代表的含义：ACL_FLOAT(f32)、ACL_FLOAT16(f16)、ACL_DOUBLE(f64)、ACL_BF16(bf16)、ACL_INT8(s8)、ACL_UINT8(u8)、ACL_INT16(s16)、ACL_UINT16(u16)、ACL_INT32(s32)、ACL_UINT32(u32)、ACL_INT64(s64)、ACL_UINT64(u64)、ACL_BOOL(bool)、ACL_COMPLEX32(c32)、ACL_COMPLEX64(c64)、ACL_COMPLEX128(c128)。
- 表格里表头和最左侧一列分别表示待推导的两个输入数据类型，表格中对应位置表示推导出的数据类型。
- NA表示这两种类型不能进行推导计算。
- 当输入数据类型为bool与其他任意数据类型（非u16、u32、u32），其推导出的数据类型为其他任意数据类型。当输入数据类型为bool与u16、u32、u64其中一个，均不支持数据类型推导。
- 当输入数据类型为u16与u16，其推导出的数据类型仍为u16。当输入数据类型为u16与非u16的任意数据类型，不支持数据类型推导。
- 当输入数据类型为u32与u32，其推导出的数据类型仍为u32。当输入数据类型为u32与非u32的任意数据类型，不支持数据类型推导。
- 当输入数据类型为u64与u64，其推导出的数据类型仍为u64。当输入数据类型为u64与非u64的任意数据类型，不支持数据类型推导。 :::
表1 常见数据类型推导关系
| 数据类型 | f32 | f16 | f64 | bf16 | s8 | u8 | s16 | s32 | s64 | c32 | c64 | c128 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| f32 | f32 | f32 | f64 | f32 | f32 | f32 | f32 | f32 | f32 | c64 | c64 | c128 |
| f16 | f32 | f16 | f64 | f32 | f16 | f16 | f16 | f16 | f16 | c32 | c64 | c128 |
| f64 | f64 | f64 | f64 | f64 | f64 | f64 | f64 | f64 | f64 | c64 | c64 | c128 |
| bf16 | f32 | f64 | f64 | bf16 | bf16 | bf16 | bf16 | bf16 | bf16 | c32 | c64 | c128 |
| s8 | f32 | f16 | f64 | bf16 | s8 | s16 | s16 | s32 | s64 | c32 | c64 | c128 |
| u8 | f32 | f16 | f64 | bf16 | s16 | u8 | s16 | s32 | s64 | c32 | c64 | c128 |
| s16 | f32 | f16 | f64 | bf16 | s16 | s16 | s16 | s32 | s64 | c32 | c64 | c128 |
| s32 | f32 | f16 | f64 | bf16 | s32 | s32 | s32 | s32 | s64 | c32 | c64 | c128 |
| s64 | f32 | f16 | f64 | bf16 | s64 | s64 | s64 | s64 | s64 | c32 | c64 | c128 |
| c32 | c64 | c32 | c64 | c32 | c32 | c32 | c32 | c32 | c32 | c32 | c64 | c128 |
| c64 | c64 | c64 | c64 | c64 | c64 | c64 | c64 | c64 | c64 | c64 | c64 | c128 |
| c128 | c128 | c128 | c128 | c128 | c128 | c128 | c128 | c128 | c128 | c128 | c128 | c128 |
| 数据类型 | f32 | f16 | f64 | bf16 | s8 | u8 | s16 | s32 | s64 | c32 | c64 | c128 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| u16 | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA |
| u32 | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA |
| u64 | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA |
推导示例
- 调用aclnnAdd接口时，如果两个输入参数的数据类型不一致，一个为float16，一个为float32，那么API内部就会将float16的数据类型转换成float32的数据类型然后进行计算。
- 调用aclnnAdd接口时，如果两个输入参数的数据类型不一致，一个为float32，一个为bool，那么API内部就会将bool的数据类型转换成float32的数据类型然后进行计算。
父主题： 基本概念
互转换关系
当一个API（如aclnnAdd、aclnnMul等）输出的Tensor数据类型与输入的数据类型推导后的计算类型不一致时，API内部就会将计算结果转换成输出类型对应的数据类型。
数据类型转换需要满足以下规则，不满足规则的将不能进行转换，调用API时会出现参数校验失败。
- 浮点数据类型：ACL_FLOAT16、ACL_FLOAT、ACL_DOUBLE、ACL_BF16间可以互相转换。
- 整型数据类型：ACL_INT8、ACL_UINT8、ACL_INT16、ACL_UINT16、ACL_INT32、ACL_UINT32、ACL_INT64、ACL_UINT64间可以互相转换。
- 整型数据类型可以往浮点类型转换。
- 浮点数据类型不可以向整型转换。
- 非BOOL型不可以往BOOL型转换。
- 复数类型：ACL_COMPLEX64、ACL_COMPLEX128间可以转换，复数类型不可以和非复数类型互转。
父主题： 基本概念
数据格式
数据格式（format）是用于描述一个多维Tensor的轴的业务语义，表示数据的物理排布格式，定义了解读数据的维度，比如1D、2D、3D、4D、5D等。一般在CNN（Convolutional Neural Network）类的API中需要给出具体的数据排布格式。
:::note 说明
- 数据格式一般形式为“ACL_FORMAT_X**XXX”，为方便描述，可简写为“X**XXX”。
- 数据格式中维度含义：N（Batch）表示批量大小、H（Height）表示特征图高度、W（Width）表示特征图宽度、C（Channels）表示特征图通道、D（Depth）表示特征图深度。 :::
常见数据格式
目前大部分算子API都是支持ND数据格式的。例如aclnnAdd接口，均标明支持的数据格式是ND（即多维Tensor的，低维度优先连续排布的规则）。
对于aclnnConvolution，该API要求输入的aclTensor设置具有业务语义的格式，而不是ND格式。此类算子，在计算过程中需要知道Tensor中的业务语义才可以进行对应的计算。例如2D卷积中，需要知道Batch维度、Channel维度、Height维度、Width维度与Tensor维度的对应关系是什么。
当调用aclCreateTensor接口的时候，根据API要求设置Tensor的数据格式，当前支持的数据格式有：
ACL_FORMAT_ND、ACL_FORMAT_NCHW、ACL_FORMAT_NHWC、ACL_FORMAT_HWCN、ACL_FORMAT_NDHWC、ACL_FORMAT_NCDHW、ACL_FORMAT_NC、ACL_FORMAT_NCL。
对于非ND的Tensor，Tensor的维度要求与format表述是一致的。例如：
- 5D的Tensor：要求为ACL_FORMAT_NCDHW、ACL_FORMAT_NDHWC或者ACL_FORMAT_ND（如果API参数说明中未标明支持ND，设置ND格式后API将会校验报错）。
- 4D的Tensor：要求为ACL_FORMAT_NCHW、ACL_FORMAT_NHWC、ACL_FORMAT_HWCN或者ACL_FORMAT_ND。
- 3D的Tensor：要求为ACL_FORMAT_NCL或者ACL_FORMAT_ND。
- 2D的Tensor：要求为ACL_FORMAT_NC或者ACL_FORMAT_ND。
- 其他维度的Tensor：要求为ACL_FORMAT_ND。
私有数据格式
除了常见的数据格式，还存在其他的数据格式，比如ACL_FORMAT_NC1HWC0、ACL_FORMAT_FRACTAL_Z、ACL_FORMAT_NC1HWC0_C04、ACL_FORMAT_FRACTAL_NZ、ACL_FORMAT_NDC1HWC0、ACL_FORMAT_FRACTAL_Z_3D等。
这些格式，属于NPU的一些私有格式，当前绝大多数的aclnn API还不支持这些格式。如果有个别API申明了支持的数据格式，请以该API实际描述为准。
父主题： 基本概念
数据结构
常用的数据结构如下，可以通过公共接口创建。
-
定义AscendCL张量数据结构，用来管理和存储类似向量、矩阵等数据。
typedef struct aclTensor aclTensor -
定义AscendCL标量数据结构，用来管理和存储标量数据（比如一个单独的数）。
typedef struct aclScalar aclScalar -
定义AscendCL整型数组数据结构，用来管理和存储由int类型数据构成的数组。
typedef struct aclIntArray aclIntArray -
定义AscendCL浮点型数组数据结构，用来管理和存储由float类型数据构成的数组。
typedef struct aclFloatArray aclFloatArray -
定义AscendCL布尔型数组数据结构，用来管理和存储由bool类型数据构成的数组。
typedef struct aclBoolArray aclBoolArray -
定义AscendCL张量列表数据结构，用来管理和存储由tensor类型数据构成的列表。
typedef struct aclTensorList aclTensorList -
定义AscendCL执行器数据结构，用来执行算子计算的容器。
typedef struct aclOpExecutor aclOpExecutor -
定义AscendCL流处理数据结构，用来管理和维护一些异步操作的执行顺序。
typedef void *aclrtStream
父主题： 基本概念
公共接口
本节罗列了单算子API执行接口定义时依赖的一些AscendCL元接口，通过这些元接口可以构建所需的数据结构，如aclTensor、aclScalar、aclIntArray等。
表1 AscendCL meta接口
| 接口名 | 接口定义 | 功能说明 | 参数说明 | 返回值 |
|---|---|---|---|---|
| aclCreateTensor | aclTensor *aclCreateTensor(const int64_t *viewDims, uint64_t viewDimsNum, aclDataType dataType, const int64_t *stride, int64_t offset, aclFormat format, const int64_t *storageDims, uint64_t storageDimsNum, void *tensorData) | 创建aclTensor。 | - viewDims（输入）：view shape的维度值。 - viewDimsNum（输入）：view shape的维度数。 - dataType（输入）：tensor的数据类型。 - strides（输入）：tensor的view的各个维度步长。 - offset（输入）：tensor首元素相对于storage的偏移。 - format（输入）：tensor的数据排布格式。 - storageDims（输入）：tensor的存储的shape的维度值。 - storageDimsNum（输入）：tensor的存储的shape的维度数。 - tensorData（输入）：tensor在Device侧的存储地址。 | 成功则返回创建好的aclTensor，否则返回nullptr。 |
| aclDestroyTensor | aclnnStatus aclDestroyTensor(const aclTensor *tensor) | 销毁aclTensor。 | tensor（输入）：需要销毁的tensor指针。 | 返回0表示成功，返回其它值表示失败。 |
| aclCreateScalar | aclScalar *aclCreateScalar(void *value, aclDataType dataType) | 创建aclScalar。 | - value（输入）：Host侧的scalar类型的指针，其指向的值会作为scalar。 - dataType（输入）：scalar的数据类型。 | 成功则返回创建好的aclScalar，否则返回nullptr。 |
| aclDestroyScalar | aclnnStatus aclDestroyScalar(const aclScalar *scalar) | 销毁aclScalar。 | scalar（输入）：需要销毁的scalar。 | 返回0表示成功，返回其它值表示失败。 |
| aclCreateIntArray | aclIntArray *aclCreateIntArray(const int64_t *value, uint64_t size) | 创建aclIntArray。 | - value（输入）：Host侧的int64_t类型的指针，其指向的值会赋给Array。 - size（输入）：整型数组的长度。 | 成功则返回创建好的aclIntArray，否则返回nullptr。 |
| aclDestroyIntArray | aclnnStatus aclDestroyIntArray(const aclIntArray *array) | 销毁aclIntArray。 | array（输入）：需要销毁的aclIntArray。 | 返回0表示成功，返回其它值表示失败。 |
| aclCreateFloatArray | aclFloatArray *aclCreateFloatArray(const float *value, uint64_t size) | 创建aclFloatArray。 | - value（输入）：Host侧的float类型的指针，其指向的值会赋给Array。 - size（输入）：浮点型数组的长度。 | 成功则返回创建好的aclFloatArray，否则返回nullptr。 |
| aclDestroyFloatArray | aclnnStatus aclDestroyFloatArray(const aclFloatArray *array) | 销毁aclFloatArray。 | array（输入）：需要销毁的aclFloatArray | 返回0表示成功，返回其它值表示失败。 |
| aclCreateBoolArray | aclBoolArray *aclCreateBoolArray(const bool *value, uint64_t size) | 创建aclBoolArray。 | - value（输入）： Host侧的bool类型的指针，其指向的值会赋给Array。 - size（输入）：布尔型数组的长度。 | 成功则返回创建好的aclBoolArray，否则返回nullptr。 |
| aclDestroyBoolArray | aclnnStatus aclDestroyBoolArray(const aclBoolArray *array) | 销毁aclBoolArray。 | array（输入）：需要销毁的aclBoolArray。 | 返回0表示成功，返回其它值表示失败。 |
| aclCreateTensorList | aclTensorList *aclCreateTensorList(const aclTensor *const *value, uint64_t size) | 创建aclTensorList。 | value（输入）： Device侧的aclTensor类型的指针，其指向的值会赋给TensorList。 size（输入）：张量列表的长度。 | 成功则返回创建好的aclTensorList，否则返回nullptr。 |
| aclDestroyTensorList | aclnnStatus aclDestroyTensorList(const aclTensorList *array) | 销毁aclTensorList。 | array（输入）：需要销毁的aclTensorList。 | 返回0表示成功，返回其它值表示失败。 |
| aclGetViewShape | aclnnStatus aclGetViewShape(const aclTensor *tensor, int64_t **viewDims, uint64_t *viewDimsNum) | 获取aclTensor的ViewShape。 | - tensor（输入）：输入的tensor。 - viewDims（输入）：返回的viewShape的dim值。 - viewDimsNum（输入）：返回的viewShape的dim维度数。 | 返回0表示成功，返回其它值表示失败。 |
| aclGetViewStrides | aclnnStatus aclGetViewStrides(const aclTensor *tensor, int64_t **stridesValue, uint64_t *stridesNum) | 获取aclTensor的viewStrides。 | - tensor（输入）：输入的tensor。 - stridesValue（输入）：返回的viewStrides的值。 - stridesNum（输入）：返回的viewStrides的strides值个数。 | 返回0表示成功，返回其它值表示失败。 |
| aclGetViewOffset | aclnnStatus aclGetViewOffset(const aclTensor *tensor, int64_t *offset) | 获取aclTensor的viewOffset。 | - tensor（输入）：输入的tensor。 - offset（输入）：返回的offset值。 | 返回0表示成功，返回其它值表示失败。 |
| aclGetFormat | aclnnStatus aclGetFormat(const aclTensor *tensor, aclFormat *format) | 获取aclTensor的format。 | - tensor（输入）：输入的tensor。 - format（输入）：返回的aclTensor的数据格式。 | 返回0表示成功，返回其它值表示失败。 |
| aclGetDataType | aclnnStatus aclGetDataType(const aclTensor *tensor, aclDataType *dataType) | 获取aclTensor的DataType。 | - tensor（输入）：输入的tensor。 - dataType（输入）：返回的aclTensor的数据类型。 | 返回0表示成功，返回其它值表示失败。 |
| aclGetIntArraySize | aclnnStatus aclGetIntArraySize(const aclIntArray *array, uint64_t *size) | 获取aclIntArray的大小。 | - array（输入）：输入的aclIntArray。 - size（输入）：返回的长度。 | 返回0表示成功，返回其它值表示失败。 |
| aclGetFloatArraySize | aclnnStatus aclGetFloatArraySize(const aclFloatArray *array, uint64_t *size) | 获取aclFloatArray的大小。 | - array（输入）：输入的aclFloatArray。 - size（输入）：返回的长度。 | 返回0表示成功，返回其它值表示失败。 |
| aclGetBoolArraySize | aclnnStatus aclGetBoolArraySize(const aclBoolArray *array, uint64_t *size) | 获取aclBoolArray的大小。 | - array（输入）：输入的aclBoolArray。 - size（输入）：返回的长度。 | 返回0表示成功，返回其它值表示失败。 |
| aclGetTensorListSize | aclnnStatus aclGetTensorListSize(const aclTensorList *tensorList, uint64_t *size) | 获取aclTensorList的大小。 | - tensorList（输入）：输入的aclTensorList。 - size（输入）：返回的长度。 | 返回0表示成功，返回其它值表示失败。 |
| aclGetStorageShape | aclnnStatus aclGetStorageShape(const aclTensor *tensor, int64_t **storageDims, uint64_t *storageDimsNum) | 取Tensor在内存上的存储shape。 | - tensor（输入）：输入的tensor对应的地址。 - storageDims（输出）：表示获取shape的地址。 - storageDimsNum（输出）：表示获取的shape的维度。 | 返回0表示成功，返回其它值表示失败。 |
父主题： 单算子API执行
在线提单