Add xrt::version APIs (#7696)

* Add xrt::version APIs

Ability to checkout XRT version and build at run-time.

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

* undef major and minor

In the GNU C Library, "major" is defined
by <sys/sysmacros.h>. For historical compatibility, it is
currently defined by <sys/types.h> as well, but we plan to
remove this soon. To use "major", include <sys/sysmacros.h>
directly. If you did not intend to use a system-defined macro
"major", you should undefine it after including <sys/types.h>.

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

* typo

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

* Work-around for CI build failure on versal

The version.h is generated at CMake time from
XRT/src/CMake/config/version.h.in by XRT/src/CMake/version.cmake.

version.cmake uses ${GIT_EXECUTABLE} to get meta data specific to
version of XRT being built, but none of the data is gathered in CI
when running `build_edge.sh -aarch versal -full` and the version.h
file is missing Git data which instead ends up as empty string.

XRT_BUILD is a define macro based on number of commits acquired from
Git, but if this value is empty the use of the macro fails.  This
PR defaults the value to 0 in hopes it gets overwritten by Git.

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

* Remove work-around which doesn't work

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

* Support concept of feature id

The feature id (xrt::version::feature()) is defined as the total
number of commits to XRT main branch.  For branches off of XRT's main
branch, the feature number is the total number of commits at the time
the branch diverged from XRT's main branch.

The feature id is computed as the difference between number of commits
on current branch and the number of commits since origin of branch from
master.

(git rev-list HEAD --count) - (git rev-list HEAD ^origin/master --count)

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

---------

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

src/CMake/config/version.h.in

@@ -1,6 +1,7 @@
 /**
  * SPDX-License-Identifier: Apache-2.0
  * Copyright (C) 2019-2021 Xilinx, Inc. All rights reserved.
+ * Copyright (C) 2023 Advanced Micro Device, Inc. All rights reserved.
  */
 
 #ifndef _XRT_VERSION_H_
@@ -26,50 +27,53 @@ static const char xrt_modified_files[] = "@XRT_MODIFIED_FILES@";
 #define XRT_VERSION_CODE XRT_VERSION(@XRT_VERSION_MAJOR@, @XRT_VERSION_MINOR@)
 #define XRT_MAJOR(code) ((code >> 16))
 #define XRT_MINOR(code) (code - ((code >> 16) << 16))
+#define XRT_PATCH @XRT_VERSION_PATCH@
+#define XRT_HEAD_COMMITS @XRT_HEAD_COMMITS@
+#define XRT_BRANCH_COMMITS @XRT_BRANCH_COMMITS@
 
-# ifdef __cplusplus
+#ifdef __cplusplus
 #include <iostream>
 #include <string>
 
-namespace xrt {
-
-class version {
- public:
-  static void print(std::ostream & output)
-  {
-     output << "       XRT Build Version: " << xrt_build_version << std::endl;
-     output << "    Build Version Branch: " << xrt_build_version_branch << std::endl;
-     output << "      Build Version Hash: " << xrt_build_version_hash << std::endl;
-     output << " Build Version Hash Date: " << xrt_build_version_hash_date << std::endl;
-     output << "      Build Version Date: " << xrt_build_version_date_rfc << std::endl;
-
-     std::string modifiedFiles(xrt_modified_files);
-     if ( !modifiedFiles.empty() ) {
-        const std::string& delimiters = ",";      // Our delimiter
-        std::string::size_type lastPos = 0;
-        int runningIndex = 1;
-        while(lastPos < modifiedFiles.length() + 1) {
-          if (runningIndex == 1) {
-             output << "  Current Modified Files: ";
-          } else {
-             output << "                          ";
-          }
-          output << runningIndex++ << ") ";
-
-          std::string::size_type pos = modifiedFiles.find_first_of(delimiters, lastPos);
-
-          if (pos == std::string::npos) {
-            pos = modifiedFiles.length();
-          }
-
-          output << modifiedFiles.substr(lastPos, pos-lastPos) << std::endl;
-
-          lastPos = pos + 1;
-        }
-     }
+namespace xrt::version {
+
+inline void
+print(std::ostream & output)
+{
+  output << "       XRT Build Version: " << xrt_build_version << std::endl;
+  output << "    Build Version Branch: " << xrt_build_version_branch << std::endl;
+  output << "      Build Version Hash: " << xrt_build_version_hash << std::endl;
+  output << " Build Version Hash Date: " << xrt_build_version_hash_date << std::endl;
+  output << "      Build Version Date: " << xrt_build_version_date_rfc << std::endl;
+
+  std::string modified_files(xrt_modified_files);
+  if (modified_files.empty())
+    return;
+
+  const std::string& delimiters = ",";      // Our delimiter
+  std::string::size_type last_pos = 0;
+  int running_index = 1;
+  while (last_pos < modified_files.length() + 1) {
+    if (running_index == 1)
+      output << "  Current Modified Files: ";
+    else 
+      output << "                          ";
+
+    output << running_index++ << ") ";
+
+    auto pos = modified_files.find_first_of(delimiters, last_pos);
+
+    if (pos == std::string::npos)
+      pos = modified_files.length();
+
+    output << modified_files.substr(last_pos, pos - last_pos) << std::endl;
+
+    last_pos = pos + 1;
   }
-};
 }
-#endif
+
+} // namespace xrt::version 
+#endif // __cplusplus
 
 #endif
+

src/CMake/version.cmake

@@ -1,6 +1,7 @@
 # SPDX-License-Identifier: Apache-2.0
 # Copyright (C) 2019-2021 Xilinx, Inc. All rights reserved.
-#
+# Copyright (C) 2023 Advanced Micro Devices, Inc. All rights reserved.
+
 # Get the branch
 execute_process(
   COMMAND ${GIT_EXECUTABLE} rev-parse --abbrev-ref HEAD
@@ -9,7 +10,6 @@ execute_process(
   OUTPUT_STRIP_TRAILING_WHITESPACE
 )
 
-
 # Get the latest abbreviated commit hash of the working branch
 execute_process(
   COMMAND ${GIT_EXECUTABLE} rev-parse --verify HEAD
@@ -18,6 +18,22 @@ execute_process(
   OUTPUT_STRIP_TRAILING_WHITESPACE
 )
 
+# Get number of commits for HEAD
+execute_process(
+  COMMAND ${GIT_EXECUTABLE} rev-list --count HEAD
+  WORKING_DIRECTORY ${XRT_SOURCE_DIR}
+  OUTPUT_VARIABLE XRT_HEAD_COMMITS
+  OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+
+# Get number of commits between HEAD and master
+execute_process(
+  COMMAND ${GIT_EXECUTABLE} rev-list --count HEAD ^origin/master
+  WORKING_DIRECTORY ${XRT_SOURCE_DIR}
+  OUTPUT_VARIABLE XRT_BRANCH_COMMITS
+  OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+
 # Get the latest abbreviated commit hash date of the working branch
 execute_process(
   COMMAND ${GIT_EXECUTABLE} log -1 --pretty=format:%cD

src/runtime_src/core/common/api/CMakeLists.txt

@@ -18,6 +18,7 @@ add_library(core_common_api_library_objects OBJECT
   xrt_profile.cpp
   xrt_queue.cpp
   xrt_system.cpp
+  xrt_version.cpp
   xrt_xclbin.cpp
   )
 

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

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2023 Advanced Micro Devices, Inc. All rights reserved.
+
+// This file implements XRT version APIs as declared in
+// core/include/experimental/xrt_version.h
+#define XRT_API_SOURCE         // exporting xrt_version.h
+#define XRT_CORE_COMMON_SOURCE // in same dll as core_common
+#include "core/include/experimental/xrt_version.h"
+#include "version.h"
+
+#ifdef major
+# undef major
+#endif
+
+#ifdef minor
+# undef minor
+#endif
+
+namespace xrt::version {
+
+unsigned int
+code()
+{
+  return XRT_VERSION_CODE;
+}
+
+unsigned int
+major()
+{
+  return XRT_MAJOR(code());
+}
+
+unsigned int
+minor()
+{
+  return XRT_MINOR(code());
+}
+
+unsigned int
+patch()
+{
+  return XRT_PATCH;
+}
+
+unsigned int
+build()
+{
+  return XRT_HEAD_COMMITS;
+}
+
+unsigned int
+feature()
+{
+  return XRT_HEAD_COMMITS - XRT_BRANCH_COMMITS;
+}
+
+} // namespace xrt::version
+
+////////////////////////////////////////////////////////////////
+// C API implementations (xrt_version.h) with "C" linkage
+////////////////////////////////////////////////////////////////
+unsigned int
+xrtVersionCode()
+{
+  return xrt::version::code();
+}
+
+unsigned int
+xrtVersionMajor()
+{
+  return xrt::version::major();
+}
+
+unsigned int
+xrtVersionMinor()
+{
+  return xrt::version::minor();
+}
+
+unsigned int
+xrtVersionPatch()
+{
+  return xrt::version::patch();
+}
+
+unsigned int
+xrtVersionBuild()
+{
+  return xrt::version::build();
+}
+
+unsigned int
+xrtVersionFeature()
+{
+  return xrt::version::feature();
+}

src/runtime_src/core/include/experimental/CMakeLists.txt

@@ -23,6 +23,7 @@ set(XRT_EXPERIMENTAL_HEADER_SRC
   xrt_queue.h
   xrt_system.h
   xrt_uuid.h
+  xrt_version.h
   xrt_xclbin.h
   xclbin_util.h
   xclbin-util.h)

src/runtime_src/core/include/experimental/xrt_version.h

@@ -0,0 +1,139 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2023 Advanced Micro Devices, Inc. All rights reserved.
+
+#ifndef xrt_version_h_
+#define xrt_version_h_
+
+#include "xrt/detail/config.h"
+
+#ifdef __cplusplus
+
+/*!
+ * @namespace xrt::version
+ *
+ * @brief
+ * APIs for version queries
+ */
+namespace xrt::version {
+
+/**
+ * code() - Returns the version code for the library.
+ *
+ * The version code is a combination of major and minor version.
+ * The major version is shifted left by 16 bits and the minor version
+ * is added.
+ */
+XRT_API_EXPORT
+unsigned int
+code();
+
+/**
+ * major() - Returns the major version for the library.
+ *
+ * The major version indicates ABI compatibility.  The major version
+ * is incremented by 1 only if a release that breaks ABI compatibility.
+ */
+XRT_API_EXPORT
+unsigned int
+major();
+
+/**
+ * minor() - Returns the minor version for the library.
+ *
+ * The minor version is incremented by 1 for each release within a
+ * major version.  
+ */
+XRT_API_EXPORT
+unsigned int
+minor();
+
+/**
+ * patch() - Returns the patch version for the library.
+ *
+ * The patch number defaults to 0 for local builds, but is otherwise
+ * controlled by CI and incremented by 1 for each build.
+ *
+ * The patch number is reset to 0 when the minor version is
+ * incremented.
+ */
+XRT_API_EXPORT
+unsigned int
+patch();
+
+/**
+ * build() - Returns the build number for the library.
+ *
+ * The build number is the total number of commits to XRT
+ * on current branch.
+ */
+XRT_API_EXPORT
+unsigned int
+build();
+
+/**
+ * feature() - Returns the feature number for the library.
+ *
+ * The feature number is the total number of commits to XRT
+ * main branch.  For branches off of XRT's main branch, the
+ * feature number is the total number of commits at the time
+ * the branch diverged from XRT's main branch.
+ */ 
+XRT_API_EXPORT
+unsigned int
+feature();
+
+} // namespace xrt::version
+
+/// @cond
+extern "C" {
+#endif
+
+/**
+ * See xrt::version::code()
+ */
+XRT_API_EXPORT
+unsigned int
+xrtVersionCode();
+
+/**
+ * See xrt::version::major()
+ */
+XRT_API_EXPORT
+unsigned int
+xrtVersionMajor();
+
+/**
+ * See xrt::version::minor()
+ */
+XRT_API_EXPORT
+unsigned int
+xrtVersionMinor();
+
+/**
+ * See xrt::version::patch()
+ */
+XRT_API_EXPORT
+unsigned int
+xrtVersionPatch();
+
+/**
+ * See xrt::version::build()
+ */
+XRT_API_EXPORT
+unsigned int
+xrtVersionBuild();
+
+/**
+ * See xrt::version::feature()
+ */
+XRT_API_EXPORT
+unsigned int
+xrtVersionFeature();
+
+/// @endcond
+#ifdef __cplusplus
+}
+#endif
+
+
+#endif