Introduction

Overview

AXCL is a C and Python language API library used for developing deep neural network inference, transcoding, and related applications on AXERA chip platforms. It provides APIs for runtime resource management, memory management, model loading and execution, and media data processing.
The logical architecture is shown below:

Concepts

The AXCL runtime library defines fundamental concepts such as Device, Context, Stream, and Task. Their relationships are illustrated below:

• Device: Hardware providing compute and media processing capabilities, connected to the host via PCIe.
  • The lifecycle of a Device begins with the first call to axclrtSetDevice.
  • Device lifecycle is managed via reference counting: axclrtSetDevice increments the count, axclrtResetDevice decrements it.
  • When reference count reaches zero, the Device resources in the process become unavailable.
  • If multiple Devices are present, memory resources are not shared across Devices.
• Context: An execution context container that manages Stream, memory, etc., tied to an application thread. Each Context belongs to a single Device. Contexts can be implicit or explicit:
  • Implicit Context (default Context):
    • Created when axclrtSetDevice specifies a device, destroyed automatically when axclrtResetDevice reference count hits zero.
    • One implicit Context per Device, cannot be destroyed via axclrtDestroyContext.
  • Explicit Context:
    • Created explicitly with axclrtCreateContext and destroyed with axclrtDestroyContext.
    • Contexts inside a process are shareable and can be switched via axclrtSetCurrentContext. It is recommended to create and destroy explicit Contexts per thread.
• Stream: Execution task stream, belongs to a Context. Tasks within the same Stream execute in order. Streams can be implicit or explicit:
  • Implicit Stream (default Stream):
    • Each Context has one implicit Stream, lifecycle tied to Context.
    • Native SDK modules (e.g., AXCL_VDEC_XXX, AXCL_SYS_XXX) use the implicit Stream.
  • Explicit Stream:
    • Created via axclrtCreateStream and destroyed via axclrtDestroyStream.
    • Becomes unusable if its parent Context is destroyed or ends, even if not explicitly destroyed.
• Task: Internal entity representing a Device execution task; not visible to applications.

Application Threads and Context

• Each application thread is bound to a Context; all Device tasks are executed within a Context.
• Each thread has one active Context at a time, bound to the Device executing that thread's tasks.
• A thread can create multiple Contexts with axclrtCreateContext, but only one is active at a given time — the most recently created.
• Within a process, axclrtSetCurrentContext binds the current thread to a Context; the last call determines the active binding.
• In multi‑threaded applications, it is recommended to create explicit Contexts per thread.
• Device switching is recommended via axclrtSetCurrentContext.