Data Formats

A data format describes the business semantics of the axes of a multidimensional tensor, indicating the physical layout format of data, such as 1D, 2D, 3D, 4D, and 5D. It is typically required in CNN (Convolutional Neural Networks) APIs to specify the exact format.

For the full data format range supported by aclTensor, see "Data Types and Operation APIs > aclFormat" in Runtime API.

For an introduction to the data format layout principles, see "Concept Principles and Terminology > Neural Networks and Operators > Data Layout Format" in Ascend C Operator Development Guide.

Usage Instructions

Currently, most operator APIs support the ND data format. For example, the aclnnAdd interface indicates that the supported data format is ND (i.e., the rule of low-dimension-first contiguous layout for multi-dimensional tensors). For aclnnConvolution, which is a CNN-type API, the input aclTensor is required to be set with a format that carries business semantics, rather than the ND format. Such operators need to understand the business semantics within the tensor during computation to perform the corresponding calculations. For instance, in 2D convolution, it is necessary to know the correspondence between the Batch dimension, Channel dimension, Height dimension, Width dimension, and the tensor dimensions.

NOTE:

• When describing the parameters of two-phase APIs, to simplify the description, the original data format “ACL_FORMAT_XXXX_” is abbreviated as "XXXX".
• Meanings of dimensions in data formats: N (Batch) indicates the batch size, H (Height) indicates the feature map height, W (Width) indicates the feature map width, C (Channels) indicates the feature map channels, D (Depth) indicates the feature map depth, and L (Length) indicates the feature map length.

Common Data Formats

When creating an aclTensor using the aclCreateTensor interface, you need to set the data format according to the API service requirements. The currently supported data formats are:

ACL_FORMAT_ND, ACL_FORMAT_NCHW, ACL_FORMAT_NHWC, ACL_FORMAT_HWCN, ACL_FORMAT_NDHWC, ACL_FORMAT_NCDHW, ACL_FORMAT_NC, ACL_FORMAT_NCL.

For non-ND tensors, the dimension requirements of the tensor must be consistent with the format representation. For example:

• 5D tensor: ACL_FORMAT_NCDHW, ACL_FORMAT_NDHWC, or ACL_FORMAT_ND is required (if ND format support is not specified in the API parameter description, setting the ND format will cause the API to report a validation error).
• 4D tensor: ACL_FORMAT_NCHW, ACL_FORMAT_NHWC, ACL_FORMAT_HWCN, or ACL_FORMAT_ND is required.
• 3D tensor: ACL_FORMAT_NCL or ACL_FORMAT_ND is required.
• 2D tensor: ACL_FORMAT_NC or ACL_FORMAT_ND is required.
• Tensors of other dimensions: ACL_FORMAT_ND is required.

Private Data Formats

In addition to the common data formats described above, there are other data formats, such as ACL_FORMAT_NC1HWC0, ACL_FORMAT_FRACTAL_Z, ACL_FORMAT_NC1HWC0_C04, ACL_FORMAT_FRACTAL_NZ, ACL_FORMAT_NDC1HWC0, and ACL_FORMAT_FRACTAL_Z_3D.

These formats are proprietary NPU formats, and most current aclnn APIs do not support them. If an individual API declares supported data formats, refer to the actual description of that API.