Specialize xrt::aie::program as specific ELF type (#8810)

* Specialize xrt::aie::program as specific ELF type

Add xrt::aie::program as a first class ELF type that is
interchangeable with xrt::elf provided the ELF represents an AIE
program.

While xrt::elf is a basic wrapper for any ELF, the xrt::aie::program
extends the APIs of xrt::elf for mining of data specific to AIE, such
as kernel meta data and extraction of control code for patching by AIEBU.

Signed-off-by: Soren Soe <[email protected]>

* Fix bad forwarding overload

Signed-off-by: Soren Soe <[email protected]>

---------

Signed-off-by: Soren Soe <[email protected]>

Author: stsoe

src/runtime_src/core/common/api/xrt_elf.cpp

@@ -3,6 +3,7 @@
 #define XCL_DRIVER_DLL_EXPORT  // exporting xrt_elf.h
 #define XRT_API_SOURCE         // exporting xrt_elf.h
 #define XRT_CORE_COMMON_SOURCE // in same dll as core_common
+#include "xrt/experimental/xrt_aie.h"
 #include "xrt/experimental/xrt_elf.h"
 #include "xrt/xrt_uuid.h"
 
@@ -144,3 +145,26 @@ get_cfg_uuid() const
 }
 
 } // namespace xrt
+
+////////////////////////////////////////////////////////////////
+// xrt::aie::program C++ API implementation (xrt_aie.h)
+////////////////////////////////////////////////////////////////
+namespace xrt::aie {
+
+void
+program::
+valid_or_error()
+{
+  // Validate that the ELF file is a valid AIE program
+}
+
+program::size_type
+program::
+get_partition_size() const
+{
+  return get_handle()->get_partition_size();
+}
+
+} // namespace xrt::aie
+  
+

src/runtime_src/core/common/api/xrt_module.cpp

@@ -6,6 +6,7 @@
 #include "core/common/config_reader.h"
 #include "core/common/message.h"
 #include "xrt/experimental/xrt_module.h"
+#include "xrt/experimental/xrt_aie.h"
 #include "xrt/experimental/xrt_elf.h"
 #include "xrt/experimental/xrt_ext.h"
 
@@ -725,6 +726,7 @@ class module_elf : public module_impl
 // module class for ELFs with os_abi - Elf_Amd_Aie2p & ELF_Amd_Aie2p_config
 class module_elf_aie2p : public module_elf
 {
+  xrt::aie::program m_program;
   // New Elf of Aie2p contain multiple ctrltext, ctrldata sections
   // sections will be of format .ctrltext.* where .* has index of that section type
   // Below maps has this index as key and value is pair of <section index, data buffer>
@@ -837,8 +839,8 @@ class module_elf_aie2p : public module_elf
       arg.dir = xrt_core::xclbin::kernel_argument::direction::input;
       // if arg has pointer(*) in its name (eg: char*, void*) it is of type global otherwise scalar
       arg.type = (str.find('*') != std::string::npos)
-               ? xrt_core::xclbin::kernel_argument::argtype::global
-               : xrt_core::xclbin::kernel_argument::argtype::scalar;
+        ? xrt_core::xclbin::kernel_argument::argtype::global
+        : xrt_core::xclbin::kernel_argument::argtype::scalar;
 
       // At present only global args are supported
       // TODO : Add support for scalar args in ELF flow
@@ -1044,25 +1046,25 @@ class module_elf_aie2p : public module_elf
       }
 
       std::string argnm{ symname, symname + std::min(strlen(symname), dynstr->get_size()) };
-      patcher::patch_info pi = patch_scheme == patcher::symbol_type::scalar_32bit_kind ?
-                               // st_size is is encoded using register value mask for scaler_32
-                               // for other pacthing scheme it is encoded using size of dma
-                               patcher::patch_info{ offset, add_end_addr, static_cast<uint32_t>(sym->st_size) } :
-                               patcher::patch_info{ offset, add_end_addr, 0 };
+      patcher::patch_info pi = patch_scheme == patcher::symbol_type::scalar_32bit_kind
+        // st_size is is encoded using register value mask for scaler_32
+        // for other pacthing scheme it is encoded using size of dma
+        ? patcher::patch_info{ offset, add_end_addr, static_cast<uint32_t>(sym->st_size) }
+        : patcher::patch_info{ offset, add_end_addr, 0 };
 
       auto key_string = generate_key_string(argnm, buf_type, sec_index);
 
       if (auto search = m_arg2patcher.find(key_string); search != m_arg2patcher.end())
         search->second.m_ctrlcode_patchinfo.emplace_back(pi);
-      else {
+      else
         m_arg2patcher.emplace(std::move(key_string), patcher{patch_scheme, {pi}, buf_type});
-      }
     }
   }
 
 public:
   explicit module_elf_aie2p(const xrt::elf& elf)
     : module_elf{elf}
+    , m_program{elf}
   {
     initialize_kernel_info();
     initialize_buf(patcher::buf_type::ctrltext, m_instr_buf_map);
@@ -1176,6 +1178,7 @@ class module_elf_aie2p : public module_elf
 // module class for ELFs with os_abi - Elf_Amd_Aie2ps
 class module_elf_aie2ps : public module_elf
 {
+  xrt::aie::program m_program;
   std::vector<ctrlcode> m_ctrlcodes;
   buf m_dump_buf; // buffer to hold .dump section used for debug/trace
 
@@ -1405,7 +1408,8 @@ class module_elf_aie2ps : public module_elf
 
 public:
   explicit module_elf_aie2ps(const xrt::elf& elf)
-    : module_elf(elf)
+    : module_elf{elf}
+    , m_program{elf}
   {
     std::vector<size_t> pad_offsets;
     initialize_column_ctrlcode(pad_offsets);
@@ -2311,8 +2315,8 @@ dump_dtrace_buffer(const xrt::module& module)
 
 } // xrt_core::module_int
 
-namespace
-{
+namespace {
+
 static std::shared_ptr<xrt::module_elf>
 construct_module_elf(const xrt::elf& elf)
 {
@@ -2327,13 +2331,14 @@ construct_module_elf(const xrt::elf& elf)
     throw std::runtime_error("unknown ELF type passed\n");
   }
 }
-}
+
+} // namespace
 
 ////////////////////////////////////////////////////////////////
 // xrt_module C++ API implementation (xrt_module.h)
 ////////////////////////////////////////////////////////////////
-namespace xrt
-{
+namespace xrt {
+
 module::
 module(const xrt::elf& elf)
 : detail::pimpl<module_impl>(construct_module_elf(elf))

src/runtime_src/core/include/xrt/experimental/xrt_aie.h

@@ -1,17 +1,85 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2021 Xilinx, Inc. All rights reserved.
+// Copyright (C) 2025 Advanced Micro Devices, Inc. All rights reserved.
+#ifndef XRT_EXPERIMENTAL_AIE_H
+#define XRT_EXPERIMENTAL_AIE_H
+#include "xrt/xrt_aie.h"
+#include "xrt/experimental/xrt_elf.h"
+
+#ifdef __cplusplus
+#include <type_traits>
+
+namespace xrt::aie {
+
 /**
- * Copyright (C) 2021 Xilinx, Inc
- * ZNYQ XRT Library layered on top of ZYNQ zocl kernel driver
+ * An aie::program object is a representaiton of a program to be executed
+ * on the AIE.  The program is an ELF file with sections and data
+ * specific to the AIE.
  *
- * Licensed under the Apache License, Version 2.0 (the "License"). You may
- * not use this file except in compliance with the License. A copy of the
- * License is located at
+ * A program is added to a hardware context either when the hardware
+ * context is contructed or by later adding the program to an existing
+ * hardware context.
  *
- *     http://www.apache.org/licenses/LICENSE-2.0
+ * An aie::program object can be created from an existing xrt::elf object
+ * provided the ELF represents an AIE program. It can also be constructed
+ * from a file or stream as provided by class xrt::elf.
  *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
- * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
- * License for the specific language governing permissions and limitations
- * under the License.
+ * The xrt::aie::program and xrt::elf are interchangable; the former
+ * can be assigned to the latter, and the former can be constructed
+ * from the latter without object slicing since the xrt::aie::program
+ * is sharing same underlying implmenentation as xrt::elf.
  */
-#include "xrt/xrt_aie.h"
+class program : public xrt::elf
+{
+  // Validate that the ELF represents an AIE program
+  XRT_API_EXPORT
+  void
+  valid_or_error();
+
+public:
+  using size_type = uint32_t;
+
+  /**
+   * program() - Create a program object using xrt::elf constructors.
+   *
+   * Construction fails if the ELF is not a valid AIE program.
+   *
+   * This constructor is enabled only for types that do not match
+   * program, this avoids forwaring reference overload
+   */
+  template <typename ArgType,
+            typename = std::enable_if_t<!std::is_same_v<std::decay_t<ArgType>, program>>>
+  explicit
+  program(ArgType&& arg)
+    : xrt::elf{std::forward<ArgType>(arg)}
+  {
+    valid_or_error();
+  }
+  
+  /**
+   * program() - Create a program object from an existing ELF.
+   *
+   * Construction fails if the ELF is not a valid AIE program.
+   */
+  explicit
+  program(xrt::elf xe)
+    : xrt::elf{std::move(xe)}
+  {
+    valid_or_error();
+  }
+
+  /**
+   * get_partition_size() - Required partition size to run the program
+   *
+   * The partition size is used to configure a hardware context such
+   * that it spans columns sufficient to run the program.
+   */
+  XRT_API_EXPORT
+  size_type
+  get_partition_size() const;
+};
+  
+} // namespace xrt::aie
+
+#endif // __cplusplus
+#endif // XRT_EXPERIMENTAL_AIE_H

src/runtime_src/core/include/xrt/experimental/xrt_elf.h

@@ -48,6 +48,12 @@ class elf : public detail::pimpl<elf_impl>
   explicit
   elf(std::istream& stream);
 
+  /**
+   * get_cfg_uuid() - Get the configuration UUID of the elf
+   *
+   * @return
+   *  The configuration UUID of the elf
+   */
   XRT_API_EXPORT
   xrt::uuid
   get_cfg_uuid() const;

tests/xrt/elf/CMakeLists.txt

@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Advanced Micro Devices, Inc. All rights reserved.
+CMAKE_MINIMUM_REQUIRED(VERSION 3.16.0)
+PROJECT(elf)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED OFF)
+set(CMAKE_VERBOSE_MAKEFILE ON)
+
+if (MSVC)
+  add_compile_options(/Zc:__cplusplus)
+endif()
+
+find_package(XRT REQUIRED HINTS ${XILINX_XRT}/share/cmake/XRT)
+message("-- XRT_INCLUDE_DIRS=${XRT_INCLUDE_DIRS}")
+
+add_executable(elf main.cpp)
+target_include_directories(elf PRIVATE ${XRT_INCLUDE_DIRS})
+target_link_libraries(elf PRIVATE XRT::xrt_coreutil)
+
+install(TARGETS elf)

tests/xrt/elf/main.cpp

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2025 Advanced Micro Devices, Inc. All rights reserved.
+
+#include "xrt/experimental/xrt_aie.h"
+#include "xrt/experimental/xrt_elf.h"
+
+#include <iostream>
+#include <string>
+#include <vector>
+
+static void
+usage()
+{
+    std::cout << "usage: %s [options] -k <bitstream>\n\n";
+    std::cout << "  --elf <file>\n";
+    std::cout << "  [-h]\n\n";
+}
+
+static void
+true_or_error(bool cond, const std::string& msg)
+{
+  if (!cond)
+    throw std::runtime_error("Error: condition failed - " + msg);
+}
+
+static void
+test_elf(const std::string& elf_fnm)
+{
+  xrt::elf elf(elf_fnm);
+}
+
+static void
+test_program(const std::string& elf_fnm)
+{
+  xrt::elf elf{elf_fnm};
+  xrt::aie::program program1{elf_fnm};
+  true_or_error(elf.get_handle() != program1.get_handle(), "expected different elf handles");
+  
+  xrt::aie::program program2{elf};
+  true_or_error(elf.get_handle() == program2.get_handle(), "expected same elf handles");
+  
+  //auto col2 = program2.get_partition_size();
+
+  xrt::aie::program program3{program2};
+  true_or_error(elf.get_handle() == program3.get_handle(), "expected same elf handles");
+
+  xrt::aie::program program4{std::move(program3)};
+  true_or_error(elf.get_handle() == program4.get_handle(), "expected same elf handles");
+}
+
+static void
+test_module(const std::string& elf_fnm)
+{
+}
+
+static int
+run(int argc, char** argv)
+{
+  if (argc < 2) {
+    usage();
+    return 1;
+  }
+
+  std::string elf_fnm;
+
+  std::vector<std::string> args{argv + 1, argv + argc};
+  std::string cur;
+  for (const auto& arg : args) {
+    if (arg == "-h") {
+      usage();
+      return 0;
+    }
+
+    if (arg[0] == '-')
+      cur = arg.substr(arg.find_first_not_of("-"));
+
+    else if (cur == "elf")
+      elf_fnm = arg;
+  }
+
+  if (elf_fnm.empty()) {
+    std::cout << "Error: ELF file not specified\n";
+    return 1;
+  }
+
+  test_elf(elf_fnm);
+  test_program(elf_fnm);
+  test_module(elf_fnm);
+
+  return 0;
+}
+
+int main(int argc, char* argv[])
+{
+  try {
+    return run(argc, argv);
+  }
+  catch (const std::exception& ex) {
+    std::cout << "Caught exception: " << ex.what() << '\n';
+  }
+  catch (...) {
+    std::cout << "Caught unknown exception\n";
+  }
+  return 1;
+}