# aiebu **Repository Path**: mirrors_Xilinx/aiebu ## Basic Information - **Project Name**: aiebu - **Description**: AIEBU - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main-ge - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2024-08-07 - **Last Updated**: 2026-09-27 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README .. _README.rst: .. comment:: SPDX-License-Identifier: MIT comment:: Copyright (C) 2024-2026 Advanced Micro Devices, Inc. ============================ AIE Binary Utilities (aiebu) ============================ This repository contains library and utilities to work with AIE *ctrlcode* Init workspace, including submodules ==================================== :: git submodule update --init --recursive Build Dependencies ================== * cmake 3.18 or above (3.24 on windows) * c++17 compiler * Boost (header only) minimum version supported is 1.76 * cxxopts (included as submodule) * ELFIO (included as submodule) Python Dependencies (optional) ------------------------------ * pylint * markdown (for generating ISA stubs and documentation) * pyyaml (for generating ISA stubs and documentation) * Jinja2 (for generating ISA stubs and documentation) * colorama (for testing) * GitPython (for testing) Build Instruction ================= Linux ----- Ubuntu minimum supported version is 24.04 :: cd build ./build.sh Windows ------- aiebu uses *hybrid* linking on Windows which involves static linking with C++ but dynamic linking with Universal C Runtime. There is no dependency on MS VCRT. :: cd build ./build22.bat Test ---- Directories ``test/cpp_test`` and ``test/cmake-test/sample`` contain sample code to show usage of public C/C++ APIs. Public Header Files ------------------- :: opt/xilinx/aiebu/include └── aiebu ├── aiebu_assembler.h ├── aiebu_error.h └── aiebu.h Compiled Libraries ------------------ By default aiebu produces a static library for static linking with clients like `XRT `_. :: opt/xilinx/aiebu/lib └── libaiebu.a Generating ISA Stubs and HTML Documentation =========================================== AIE4 ctrlcode ISA stubs and documentation can be generated on Linux if desired. It requires python packages listed above in Python Dependencies above. Linux ----- :: cd build/Release make isa-spec-gen ELF Format for AIE Architectures ================================ aiebu generates ELF files for AIE ctrlcode. The ELF header contains OS/ABI and ABI version fields that identify the target architecture and ELF format version. OS/ABI Values ------------- The OS/ABI field (``e_ident[EI_OSABI]``) identifies the target AIE architecture. Values are chosen with high Hamming distance for robustness against bit flips. .. list-table:: OS/ABI Values :header-rows: 1 :widths: 25 15 60 * - Architecture - Value (Hex) - Description * - aie2ps_group - 0x46 (70) - Legacy group ELF for AIE2PS/AIE4 family * - aie2p - 0x45 (69) - AIE2P architecture * - aie2ps - 0x40 (64) - AIE2PS specific (config with ``.target``) * - aie4 - 0x4B (75) - AIE4 architecture * - aie4a - 0x56 (86) - AIE4A architecture variant * - aie4z - 0x69 (105) - AIE4Z architecture variant ELF ABI Version --------------- The ABI version field (``e_ident[EI_ABIVERSION]``) uses major.minor encoding: upper nibble = major version, lower nibble = minor version. .. list-table:: ELF ABI Version Values :header-rows: 1 :widths: 25 15 60 * - Version - Value (Hex) - Description * - Non-config - 0x02 (0.2) - Non-config ELF (all architectures) * - Legacy config (AIE2PS/AIE4) - 0x03 (0.3) - Config ELF without ``.target`` directive * - AIE2P config (legacy) - 0x10 (1.0) - Legacy AIE2P config ELF (read-only, no longer written) * - Config with .target - 0x20 (2.0) - Config ELF with ``.target`` directive or AIE2/AIE2P config Behavior by Target Option ------------------------- The following table shows how the ``-t`` option and ``.target`` directive affect ELF version and OS/ABI: .. list-table:: ELF Output by Target :header-rows: 1 :widths: 30 20 15 35 * - -t Option - .target in ASM - ELF Version - OS/ABI * - aie2ps/aie4 (non-config) - Any (ignored) - 0x02 - aie2ps_group (0x46) * - aie2ps_config/aie4_config - Not present - 0x03 - aie2ps_group (0x46) * - aie2ps_config/aie4_config - Present - 0x20 - Based on .target value * - aie2_config/aie2p_config - N/A (binary input) - 0x20 - aie2p (0x45) * - aie2/aie2p (non-config) - N/A (binary input) - 0x02 - aie2p (0x45) **Key points:** * Non-config ELFs always use version 0x02, regardless of ``.target`` directive * Config ELFs use version 0x20 only when ``.target`` directive is present * Version 0x20 enables architecture-specific OS/ABI values Version and OS/ABI Compatibility -------------------------------- ELF readers use the ABI version to determine valid OS/ABI values: * **Version 0x02 (non-config)**: OS/ABI must be ``aie2ps_group`` (0x46) or ``aie2p`` (0x45). Used for all non-config ELFs. * **Version 0x03 (legacy config)**: OS/ABI must be ``aie2ps_group`` (0x46). Used for AIE2PS/AIE4 config ELFs without ``.target`` directive. * **Version 0x10 (AIE2P config - legacy)**: OS/ABI must be ``aie2p`` (0x45). Legacy config for AIE2P. No longer written by assembler; supported for reading existing ELF files only. * **Version 0x20 (config with .target)**: All OS/ABI values are valid (``aie2ps``, ``aie2p``, ``aie2ps_group``, ``aie4``, ``aie4a``, ``aie4z``). Used for config ELFs with ``.target`` directive or AIE2/AIE2P config. The ``.target`` directive in assembly source determines whether the new config format (version 0x20) is used. For config ELFs, when ``.target`` is present, the assembler validates it against the ``-t`` command-line option and sets the specific OS/ABI value. Non-config ELFs always use legacy values regardless of ``.target`` directive. Constants Definition -------------------- All OS/ABI and ELF version constants are defined in a single header file: ``src/cpp/elf/aie_elf_constants.h`` This file contains: * ``osabi_aie2ps_group`` (0x46) - Legacy group ELF * ``osabi_aie2p`` (0x45) - AIE2P * ``osabi_aie2ps`` (0x40) - AIE2PS specific * ``osabi_aie4`` (0x4B) - AIE4 * ``osabi_aie4a`` (0x56) - AIE4A * ``osabi_aie4z`` (0x69) - AIE4Z * ``elf_version_legacy`` (0x02) - Non-config * ``elf_version_legacy_config`` (0x03) - Legacy config * ``elf_version_aie2p_config`` (0x10) - Legacy AIE2P config (read-only) * ``elf_version_config`` (0x20) - Config with .target