文档

AscendCL API Call Sequence

This section describes the process of calling AscendCL APIs and the header and library files required for calling AscendCL APIs.

API Call Sequence

By calling AscendCL APIs, you can develop applications that provide functions such as model inference , media data processing, and single-operator execution. These functions can exist independently or in combinations. The following figure shows the overall sequence of calling AscendCL APIs to develop AI apps.

Figure 1 API call sequence

The figure briefs the API calls in typical scenarios. If the size of the input image does not meet the model requirements, media data processing is required. To implement model inference, the model needs to be loaded first. On the completion of model inference, the model needs to be unloaded. After model inference, the inference result needs to be postprocessed for displaying the class indexes corresponding to the top confidence values.

  1. Initialize AscendCL.

    Call aclInit to initialize AscendCL.

  2. Allocate runtime resources.

    For details, see Runtime Resource Allocation and Deallocation.

  3. Process app services.
    • Model inference
      1. Load the model.

        For the API call sequence, see Loading a Model.

        Before loading a model, ensure that you have the required offline model adapted to the Ascend AI Processor. For details about how to build a model, see Building a Model.

      2. (Optional) Process media data, including JPEG image and video decoding, image cropping, resizing, format conversion, and JPEG image encoding.

        For the API call sequence, see Media Data Processing (Including Images and Videos).

      3. Run model inference to implement functions such as image classification and target recognition.

        For the API call sequence, see Running a Model.

      4. (Optional) Postprocess the model inference result as required. For example, you can export the inference result to a file and look up in the inference result for the class indexes with top confidence values using single-operators.
      5. Call aclmdlUnload to unload your model.
    • Single-Operator Execution

      If your AI app involves not only model inference but also mathematical operations such as Basic Linear Algebra Subprogram (BLAS) and data type conversion, use single-operator calling when using AscendCL APIs. In this way, you can avoid additional model building and training. You can also use single-operator calling to verify the functions of a custom operator.

      For the API call sequence, see Single-Operator Call Sequence.

  4. Deallocate runtime resources.

    When data processing is complete, destroy runtime allocations in sequence. For details about the API call sequence, see Runtime Resource Allocation and Deallocation.

  5. Deinitialize AscendCL.

    Call aclFinalize to deinitialize AscendCL.

Memory allocation and deallocation, data transfer via memory copy, and data type creation and destruction are the most frequent calls across the app development workflow, and therefore are not thoroughly illustrated in the flowchart. For details about memory allocation and deallocation, and memory copy APIs, see Memory Management. For details about data type creation and destruction APIs, see acltdtStopChannel.

Dependent Header Files and Library Files

Include the dependency header files based on the AscendCL APIs to be called. Refer to following table for details.

The AscendCL header file is stored in the “${INSTALL_DIR}/include/ directory, and the AscendCL library file is stored in the “${INSTALL_DIR}/lib64/ directory. Replace ${INSTALL_DIR} with the actual CANN component directory. If the Ascend-CANN-Toolkit package is installed as the root user, the CANN component directory is /usr/local/Ascend/ascend-toolkit/latest.

When building code based on the AscendCL APIs, depend on the corresponding library files based on the included header files. If redundant .so files (such as libascendcl.a) are referenced, version functions may be abnormal or compatibility issues may occur during version update.

Table 1 Header files

Header File

Description

Matching Library

acl/acl_base.h

Declares basic data types (such as aclDataBuffer and aclTensorDesc) and their operation APIs, enumerations (such as aclFormat), and log management APIs.

libascendcl.so

acl/acl.h

Has already included acl/acl_mdl.h, acl/acl_rt.h, and acl/acl_op.h. Once the acl.h file is included, APIs related to initialization/deinitialization, device management, group management, context management, stream management, synchronization, memory management, model loading and execution, single-operator execution (some of the APIs) can be referenced.

libascendcl.so

acl/acl_prof.h

Declares the Profiling configuration APIs.

libmsprofiler.so

NOTE:

libascendcl.so is supported in earlier versions to avoid compatibility issues. However, it will be removed in later versions. Therefore, you are advised to use libmsprofiler.so to ensure compatibility with later versions.

acl/ops/acl_cblas.h

Declares the CBLAS APIs.

libacl_cblas.so

acl/ops/acl_dvpp.h

Declares the media data processing V1 APIs.

libacl_dvpp.so

acl/ops/acl_fv.h

Declares the feature vector search APIs.

Atlas 200/300/500 Inference Product : APIs declared in this header file cannot be referenced.

Atlas Training Series Product : APIs declared in this header file cannot be referenced.

libacl_retr.so

acl/acl_op_compiler.h

Declares the APIs, data types, and enumerations related to online operator compilation such as aclopCompile, aclopCompileAndExecute, and aclSetCompileopt.

libacl_op_compiler.so

acl/acl_tdt.h

Declares the tensor data transfer APIs.

Atlas 200/300/500 Inference Product : APIs declared in this header file cannot be referenced.

libacl_tdt_channel.so

acl/acl_tdt_queue.h

Declares the shared queue management and shared buffer management APIs.

libacl_tdt_queue.so

acl/dvpp/hi_dvpp.h

Declares the media data processing V2 APIs.

libacl_dvpp_mpi.so

In the acl/media directory:

hi_mpi_vi.h

hi_common_vi.h

hi_common_dis.h

hi_common_gdc.h

hi_media_common.h

hi_media_type.h

hi_mpi_sys.h

Declares the video input (VI) data obtaining APIs.

Atlas 200/300/500 Inference Product : APIs declared in this header file cannot be referenced.

Atlas Training Series Product : APIs declared in this header file cannot be referenced.

libacl_vi_mpi.so

libacl_dvpp_mpi.so

In the acl/media directory:

hi_mpi_isp.h

hi_common_isp.h

hi_common_3a.h

hi_mpi_ae.h

hi_common_ae.h

hi_mpi_awb.h

hi_common_awb.h

hi_common_sns.h

hi_media_common.h

hi_media_type.h

hi_mpi_sys.h

Declares the image signal processing (ISP) system control APIs.

Atlas 200/300/500 Inference Product : APIs declared in this header file cannot be referenced.

Atlas Training Series Product : APIs declared in this header file cannot be referenced.

libacl_isp_ae_mpi.so

libacl_isp_awb_mpi.so

libacl_isp_mpi.so

libacl_dvpp_mpi.so

In the acl/media directory:

hi_mpi_vpss.h

hi_media_common.h

hi_media_type.h

hi_mpi_sys.h

Declares the video process sub-system (VPSS) image processing APIs.

Atlas 200/300/500 Inference Product : APIs declared in this header file cannot be referenced.

Atlas Training Series Product : APIs declared in this header file cannot be referenced.

libacl_vpss_mpi.so

libacl_dvpp_mpi.so

acl/media/hi_mipi_rx.h

Declares the MIPI RX ioctl command word.

Atlas 200/300/500 Inference Product : APIs declared in this header file cannot be referenced.

Atlas Training Series Product : APIs declared in this header file cannot be referenced.

-

In the acl/media directory:

hi_mpi_audio.h

hi_common_aio.h

Declares the audio input and output APIs.

Atlas 200/300/500 Inference Product : APIs declared in this header file cannot be referenced.

Atlas Training Series Product : APIs declared in this header file cannot be referenced.

libacl_audio_mpi.so

acl/media/hi_acodec.h

Declares the volume adjusting command word.

Atlas 200/300/500 Inference Product : APIs declared in this header file cannot be referenced.

Atlas Training Series Product : APIs declared in this header file cannot be referenced.

-

In the acl/media directory:

hi_common_vo.h

hi_mpi_vo.h

Declares the video output APIs.

Atlas 200/300/500 Inference Product : APIs declared in this header file cannot be referenced.

Atlas Training Series Product : APIs declared in this header file cannot be referenced.

libacl_vo_mpi.so

acl/media/hi_mpi_hdmi.h

Declares the HDMI APIs for connecting to peripherals.

Atlas 200/300/500 Inference Product : APIs declared in this header file cannot be referenced.

Atlas Training Series Product : APIs declared in this header file cannot be referenced.

libacl_hdmi_mpi.so

acl/media/hi_mpi_tde.h

Declares the TDE APIs for graphics drawing.

Atlas 200/300/500 Inference Product : APIs declared in this header file cannot be referenced.

Atlas Training Series Product : APIs declared in this header file cannot be referenced.

libacl_tde_mpi.so

acl/media/hifb.h

Declares APIs for managing overlaid graphics layers.

Atlas 200/300/500 Inference Product : APIs declared in this header file cannot be referenced.

Atlas Training Series Product : APIs declared in this header file cannot be referenced.

-

aclnn/acl_meta.h

Defines the AscendCL meta APIs on which single-operator API execution depends, which can be used to build different data structures, such as aclTensor, aclScalar, and aclIntArray.

libnnopbase.so

aclnn/aclnn_base.h

Defines the common base APIs for single-operator API execution, that is, aclnnInit and aclnnFinalize.

libnnopbase.so

aclnnop/aclnn_*.h

(* indicates the operator name.)

NOTE:

The path of the NN/fusion operator header file will be changed from aclnnop/level2/aclnn_*.h to aclnnop/aclnn_*.h. You are advised to use the new path in later versions to prevent compatibility issues.

Defines APIs for single-operator API execution, such as NN and fusion operator APIs.

Atlas 200/300/500 Inference Product : APIs declared in this header file cannot be referenced.
  • Dynamic library: libopapi.so (which can be classified into the following domains and installed as required)
    • libaclnn_ops_infer.so (network operator inference library)
    • libaclnn_ops_train.so (network operator training library)
    • libaclnn_math.so (mathematical operator library)
    • libaclnn_rand.so (random number operator library)
  • Static library:
    • libopmaster_static.a (Tiling and InferShape libraries)
    • libaclnn_ops_infer_static.a (network operator inference library)
    • libaclnn_ops_train_static.a (network operator training library)
    • libaclnn_math_static.a (mathematical operator library)
    • libaclnn_rand_static.a (random number operator library)
NOTICE:
  • If you do not want the service functions, performance, and accuracy of the installed operator binary package or built model to change due to version changes, you can use the static library for deployment.
  • When Ascend-CANN-Kernel is deployed, --install installs all files except the static library, --devel installs the dynamic and static libraries, and --feature installs the domain-specific operator library. For details about the installation modes, see Appendix A: Reference > Parameter Description in CANN Software Installation Guide.
  • For details about the operator build and run process, see Sample Code for Calling NN or Fused Operator APIs.

In the acldvppop directory:

acldvpp_base.h

acldvpp_op_api.h

Defines the functional APIs of DVPP operators.

Atlas 200/300/500 Inference Product : APIs declared in this header file cannot be referenced.

Atlas Training Series Product : APIs declared in this header file cannot be referenced.

libacl_dvpp_op.so