Documentation

Overview

This section provides an overview of programming APIs, common APIs, and general descriptions. For details about the APIs, see Ascend C API.

Ascend C provides a group of class library APIs, and you can use the standard C++ syntax and class library APIs for programming. Ascend C programming class library APIs are classified into the following types:

  • Kernel APIs: implement the operator kernel function, including:
    • Basic data structures: basic data structures used in kernel APIs, such as GlobalTensor and LocalTensor.
    • Basic APIs: implement abstract hardware capabilities and open chip capabilities to ensure completeness and compatibility. APIs marked as Instruction Set Architecture Special Interface (ISASI, hardware architecture-related APIs) do not guarantee compatibility across hardware versions.
    • High-level APIs: implement common computing algorithms to improve programming and development efficiency based on basic APIs. High-level APIs include math library, Matmul, Softmax, and other APIs. High-level APIs can ensure compatibility.
  • Host APIs:
    • Tiling APIs: provide tiling parameters required for kernel computation.
    • Ascend C operator prototype registration and management APIs: define and register the Ascend C operator prototype.
    • Tiling data structure registration APIs: define and register the TilingData structure of the Ascend C operator.
    • Platform information acquisition APIs: provide functions to obtain hardware platform information, such as the number of platform cores, to support tiling computation during tiling function implementation on the host.
  • Operator debugging APIs: used for operator debugging, including twin debugging and performance debugging.

Basic data structures and APIs are required for Ascend C operator programming on the host. For details, see Basic Data Structures and APIs. Runtime APIs are required for operator calling after operator development. For details, see "AscendCL API Reference" in CANN AscendCL Application Software Development Guide (C&C++).

Basic APIs are classified into the following types:
  • Compute APIs, including scalar compute APIs, vector compute APIs, and matrix compute APIs, are used to call the Scalar Unit, Vector Unit, and Cube Unit to perform computation.
  • Data movement APIs. The compute APIs perform computation based on data in local memory. Therefore, data needs to be moved from global memory to local memory, computed by calling the compute APIs, and then moved from local memory to global memory. The APIs that move data are called data movement APIs, for example, the DataCopy API.
  • Memory management APIs, such as the AllocTensor and FreeTensor APIs, are used to allocate and manage memory.
  • Synchronization control APIs, such as the EnQue and DeQue APIs, are used to implement communication and synchronization between tasks. Different API instructions may depend on each other. It can be learned from Hardware Architecture Abstraction that different instructions are executed asynchronously in parallel. To ensure that instructions in different instruction queues are executed according to correct logic, synchronization instructions need to be sent to different units. The synchronization control APIs complete the process of issuing synchronization instructions internally. You do not need to pay attention to the internal implementation logic. Instead, you can simply use the APIs to complete the process.
  • Instruction Set Architecture Special APIs (ISASIs) are related to the hardware architecture. This type of APIs cannot ensure cross-hardware version compatibility.

Compute APIs involves the following computation methods based on data operation methods:

  • Computation of the entire tensor: This type of computation is implemented through operator overloading. Operators (+, -, *, /, |, &, <, >, <=, >=, ==, !=) are supported to simplify the computation. Example: 
    dst=src1+src2
  • Computation of the first n data elements of a tensor: Computes the continuous n data elements of the source operand and continuously writes the data to the destination operand to solve the continuous computing problem of the one-dimensional tensor. Example: 
    Add(dst, src1, src2, n);
  • High-dimensional tensor sharding computation: Flexible compute APIs can make full use of the hardware advantages and support the dataBlockStride, repeatStride, and mask operations for each operand. For details about dataBlockStride, repeatStride, and mask, see Common Parameters.

The following figure uses vector addition as an example to show the characteristics of these computation methods.

Figure 1 Characteristics of computation methods of compute APIs

Header file directory of Ascend C APIs:

  • Basic APIs: {install_path}/include/ascendc/basic_api/interface
  • High-level APIs: (Note that if the APIs contained in the following header file directories are not declared in the documentation, they are called indirectly, and developers do not need to pay attention to them.)
    • {install_path}/include/ascendc/highlevel_api/lib
    • {install_path}/include/tiling

{install_path} indicates the CANN installation directory.

Parent topic: Programming APIs