AI Engine Driver External Interfaces - 2024.1 English

AI Engine System Software Driver Reference Manual (UG1642)

Document ID
Release Date
2024.1 English

There are three sets of external interfaces from the AI Engine driver:

  • AI Engine configuration
    • Processing core control, enable/disable, reset
    • ELF loading
    • Stream connection
    • Events and errors configuration and broadcasting and interrupt configuration
    • PL interface configuration
    • Tile DMA configuration
    • Tile locks configuration
    • AI Engine partition reset
    • AI Engine memory zeroization
    • Unused tiles- gating
    • ECC scrubbing configuration
  • Runtime data sharing
    • AI Engine interface tiles DMA configuration
    • Synchronization with locks
    • Helper function to allocate memory
  • Runtime monitor, debug, and trace APIs
    • Errors and events handling
    • Performance counter-configuration
    • Event trace configuration

The AI Engine embedded software driver is split into two sides: AI Engine driver client APIs and AI Engine I/O backend. The AI Engine driver client APIs provide cross OS and platforms APIs for applications and other libraries such as AI Engine compiler or Xilinx Runtime, to configure, program, and monitor AI Engine. The AI Engine driver backends provide OS and platform dependent implementations to access AI Engine hardware.

On Linux, AI Engine driver backend manages AI Engine hardware through the AI Engine Linux kernel driver. The Linux kernel AI Engine driver supports standard Linux file operations and sysfs. The applications or libraries can request AI Engine tile access, inquire AI Engine status, profile AI Engine usage, and debug AI Engine at runtime through Linux device file operations and sysfs.

Figure 1. AI Engine Driver External Interface to Application

With different I/O backends, the AI Engine driver functions can be used on different platforms and OSs, which can be the bare-metal platform with direct I/O backend, Linux OS with Linux backend, CDO generator with CDO backend, and host simulator with simulator backend. Also, it can be extended to other backends. For example, AI Engine supports control packets so that it is possible to stream in configuration and data to AI Engine. It is possible to extend the AI Engine backend to generate control packets.

The high-level tool, such as AI Engine compiler, defines configuration sequence and generates configuration control file and ELFs. You can manually implement the control application using direct calls and compile the ELF using the low level compiler. The following figures show the AI Engine configuration file generation and the runtime control. The AI Engine compiler generates AI configuration and runtime control sequence.

Figure 2. ELF / Configuration Generation at Build Time

This is the AI Engine control code generated implementing the init, run, and end graph APIs for the specific graph objects present in the program. This file is linked with the application main to create a PS thread for the simulator and bare-metal.
This is the AI Engine control code generated implementing the init, run, and end graph APIs for the specific graph objects present in the program. This file is linked with the application main to create a PS thread for the Linux application.
Figure 3. Generated AI Engine Graph Control Sequence
Figure 4. ELF Loading CDO

The aie_control.cpp is generated from the user-defined graph by the AI Engine compiler. The user-defined graph defines the connections between the AI Engine cores. The aie_control.cpp defines the configuration sequence, the enabling sequence, and the cleanup sequence. It can be compiled to run on the target. It can also be compiled on the host to generate the CDO. For more information about graph coding and complication, see the AI Engine Tools and Flows User Guide (UG1076).

If the AI Engine control application runs on PS processors, it can directly call the AI Engine driver APIs to configure AI Engine cores, and stream connections. If you choose to configure AI Engine with CDO, CDO and AI Engine ELFs can be loaded as part of boot PDI at boot time, or they can be loaded as partial PDI with FPGA manager at runtime. For Linux runtime, the partial PDI loads with FPGA manager.

Once the graph is set up, during runtime, the AI Engine embedded software driver plays a pivotal role in coordinating the application. It enables the application to dynamically adjust runtime parameters through XRT APIs. This facilitates the transfer of data between the application and AI Engine tiles, monitoring of events, errors, and the status of cores and DMAs, and, when necessary, resetting AI Engine tiles.