Create a cmake API for O_RAN SC xran forked repo

* create the xran forked repo as a cmake external project - easier to maintain and track the changes
  we applied to the original repo
* add xran_DOWNLOAD option - clones and builds latest supported K release
* update the FHI README for K release

Signed-off-by: Teodora Vladić <teodora.vladic@openairinterface.org>

cmake_targets/tools/MODULES/Findxran.cmake

@@ -46,13 +46,7 @@
 # ``xran_LIBRARY``
 #   The path to the xran library.
 
-option(xran_LOCATION "directory of XRAN library" "")
+set(CACHE{xran_LOCATION} TYPE PATH HELP "directory of XRAN library" VALUE "")
-if (NOT xran_LOCATION)
-  message(FATAL_ERROR "xran_LOCATION required")
-endif()
-if (NOT EXISTS ${xran_LOCATION})
-  message(FATAL_ERROR "no such directory: ${xran_LOCATION}")
-endif()
 
 find_path(xran_INCLUDE_DIR
   NAMES
@@ -73,16 +67,14 @@ find_library(xran_LIBRARY
   PATH_SUFFIXES build api
   NO_DEFAULT_PATH
 )
-if (NOT xran_LIBRARY)
-  message(FATAL_ERROR "could not detect xran build artifacts at ${xran_LOCATION}/build")
-endif()
 
 set(xran_VERSION_FILE "${xran_LOCATION}/../app/src/common.h")
-if(NOT EXISTS ${xran_VERSION_FILE})
+if(EXISTS ${xran_VERSION_FILE})
-  message(FATAL_ERROR "could not find xran version file at ${xran_VERSION_FILE}")
+  file(STRINGS ${xran_VERSION_FILE} xran_VERSION_LINE REGEX "^#define[ \t]+VERSIONX[ \t]+\"[a-z_.0-9]+\"$")
+else()
+  set(xran_VERSION_LINE "UNKNOWN")
 endif()
 
-file(STRINGS ${xran_VERSION_FILE} xran_VERSION_LINE REGEX "^#define[ \t]+VERSIONX[ \t]+\"[a-z_.0-9]+\"$")
 string(REGEX REPLACE "^#define[ \t]+VERSIONX[ \t]+\"([a-z_.0-9]+)\"$" "\\1" xran_VERSION_STRING "${xran_VERSION_LINE}")
 if (xran_VERSION_STRING MATCHES "^oran_e_maintenance_release_v")
   string(REGEX REPLACE "oran_e_maintenance_release_v([0-9]+).([0-9]+)" "5.\\1.\\2" xran_VERSION ${xran_VERSION_STRING})
@@ -93,9 +85,8 @@ elseif(xran_VERSION_STRING MATCHES "^oran_k_release_v")
 elseif(xran_VERSION_STRING MATCHES "^oran_bronze_release_v")
   string(REGEX REPLACE "oran_bronze_release_v([0-9]+).([0-9]+)" "2.\\1.\\2" xran_VERSION ${xran_VERSION_STRING})
 else()
-  message(FATAL_ERROR "unrecognized xran version string: ${xran_VERSION_STRING}")
+  set(xran_VERSION "UNKNOWN")
 endif()
-message(STATUS "Found xran release ${xran_VERSION_STRING} (v${xran_VERSION})")
 unset(xran_VERSION_LINE)
 unset(xran_VERSION_STRING)
 unset(xran_VERSION_FILE)

doc/ORAN_FHI7.2_Tutorial.md

@@ -72,9 +72,9 @@ Tested libxran releases:
 | Vendor                                  |
 |-----------------------------------------|
 | `oran_f_release_v1.0`                   |
+| `oran_k_release_v1.0`                   |
 
-
+**Note**: The libxran driver of OAI identifies the above F release version as "6.1.0" (F is the sixth letter, then 1.0), and the above K release as "11.1.0".
-**Note**: The libxran driver of OAI identifies the above F release version as "6.1.0" (F is the sixth letter, then 1.0).
 
 ### Configure your server
 
@@ -274,7 +274,7 @@ timedatectl set-ntp false
 
 ### DPDK (Data Plane Development Kit)
 
-Download DPDK version 20.11.9.
+Download DPDK version 20.11.9 (F release) or 24.11.4 (K release).
 
 ```bash
 # on debian
@@ -282,7 +282,8 @@ sudo apt install wget xz-utils libnuma-dev
 # on Fedora/RHEL
 sudo dnf install wget xz numactl-devel
 cd
-wget http://fast.dpdk.org/rel/dpdk-20.11.9.tar.xz
+wget http://fast.dpdk.org/rel/dpdk-20.11.9.tar.xz # F release
+wget http://fast.dpdk.org/rel/dpdk-24.11.4.tar.xz # K release
 ```
 
 #### DPDK Compilation and Installation
@@ -290,10 +291,11 @@ wget http://fast.dpdk.org/rel/dpdk-20.11.9.tar.xz
 ```bash
 # Installing meson : it should pull ninja-build and compiler packages
 # on debian
-sudo apt install meson
+sudo apt install python3-pyelftools meson
 # on Fedora/RHEL
-sudo dnf install meson
+sudo dnf install python3-pyelftools meson
-tar xvf dpdk-20.11.9.tar.xz && cd dpdk-stable-20.11.9
+tar xvf dpdk-20.11.9.tar.xz && cd dpdk-stable-20.11.9 # F release
+tar xvf dpdk-24.11.4.tar.xz && cd dpdk-stable-24.11.4 # K release
 
 meson build
 ninja -C build
@@ -359,7 +361,8 @@ pkg-config --libs libdpdk --static
 Go back to the version folder you used to build and install
 
 ```
-cd ~/dpdk-stable-20.11.9
+cd ~/dpdk-stable-20.11.9 # F release
+cd ~/dpdk-stable-24.11.4 # K release
 sudo ninja deinstall -C build
 ```
 
@@ -384,6 +387,13 @@ git checkout oran_f_release_v1.0
 git apply ~/openairinterface5g/cmake_targets/tools/oran_fhi_integration_patches/F/oaioran_F.patch
 ```
 
+#### K release
+```bash
+git clone https://github.com/openairinterface/o-du-phy.git ~/phy
+cd ~/phy
+git checkout <desired-tag> # shall match a variable `K_VERSION`
+```
+
 Compile the fronthaul interface library by calling `make` and the option
 `XRAN_LIB_SO=1` to have it build a shared object. Note that we provide two
 environment variables `RTE_SDK` for the path to the source tree of DPDK, and
@@ -398,6 +408,7 @@ This feature is intended to enable experiments and future improvements on Arm sy
 cd ~/phy/fhi_lib/lib
 make clean
 WIRELESS_SDK_TOOLCHAIN=gcc RTE_SDK=~/dpdk-stable-20.11.9/ XRAN_DIR=~/phy/fhi_lib make XRAN_LIB_SO=1 # F release
+WIRELESS_SDK_TOOLCHAIN=gcc RTE_SDK=~/dpdk-stable-24.11.4/ XRAN_DIR=~/phy/fhi_lib make XRAN_LIB_SO=1 # K release
 ...
 [AR] build/libxran.so
 ./build/libxran.so
@@ -483,7 +494,10 @@ Note that you might also call cmake directly instead of using `build_oai`:
 ```
 cd ~/openairinterface5g
 mkdir build && cd build
+# build RAN after manually building xran F or K release
 cmake .. -GNinja -DOAI_FHI72=ON -Dxran_LOCATION=$HOME/phy/fhi_lib/lib
+# build RAN and xran K release automatically
+cmake .. -GNinja -DOAI_FHI72=ON -Dxran_DOWNLOAD=ON
 ninja nr-softmodem oran_fhlib_5g params_libconfig
 ```
 
@@ -1636,6 +1650,8 @@ PKG_CONFIG_PATH=/opt/mplane-v2/lib/pkgconfig cmake .. -GNinja -DOAI_FHI72=ON -DO
 ninja nr-softmodem oran_fhlib_5g_mplane params_libconfig
 ```
 
+Note: instead of setting `xran_LOCATION`, feel free to use `xran_DOWNLOAD` option for automatic xran K release build.
+
 ### Start the gNB
 Run the `nr-softmodem` from the build directory:
 ```bash

radio/fhi_72/CMakeLists.txt

@@ -21,15 +21,54 @@ add_library(oran_fhlib_5g MODULE
 set(F_VERSION 6.1.9)
 set(K_VERSION 11.1.1)
 
-find_package(xran REQUIRED)
+add_boolean_option(xran_DOWNLOAD OFF "Download and build xran library" OFF)
-if(xran_VERSION VERSION_GREATER_EQUAL 5 AND xran_VERSION VERSION_LESS 6)
+
-  message(FATAL_ERROR "xran E release not supported starting from tag 2026.w08.\nPlease switch to F version ${F_VERSION}")
+find_package(xran)
-elseif(xran_VERSION VERSION_EQUAL F_VERSION)
+if(xran_FOUND)
-  target_compile_definitions(oran_fhlib_5g PRIVATE F_RELEASE)
+  if(xran_VERSION VERSION_GREATER_EQUAL 5 AND xran_VERSION VERSION_LESS 6)
-elseif(xran_VERSION VERSION_EQUAL K_VERSION)
+    message(FATAL_ERROR "xran E release not supported starting from tag 2026.w08.\nPlease switch to F version ${F_VERSION} or K version ${K_VERSION}")
+  elseif(xran_VERSION VERSION_EQUAL F_VERSION)
+    target_compile_definitions(oran_fhlib_5g PRIVATE F_RELEASE)
+  elseif(xran_VERSION VERSION_EQUAL K_VERSION)
+    if(dpdk_VERSION VERSION_LESS 22)
+      message(FATAL_ERROR "DPDK version miniminum 22 required for K release, but found ${dpdk_VERSION}")
+    endif()
+    target_compile_definitions(oran_fhlib_5g PRIVATE K_RELEASE)
+  else()
+    message(FATAL_ERROR "Found xran version ${xran_VERSION} but needed ${F_VERSION} (F release) or ${K_VERSION} (K release)")
+  endif()
+elseif(NOT xran_FOUND AND xran_DOWNLOAD)
+  if(dpdk_VERSION VERSION_LESS 22)
+    message(FATAL_ERROR "DPDK version miniminum 22 required for K release, but found ${dpdk_VERSION}")
+  endif()
+  include(ExternalProject)
+  set(xran_DIR "${CMAKE_BINARY_DIR}/.deps/src/extern_xran/fhi_lib/lib")
+  ExternalProject_Add(extern_xran
+      PREFIX ${CMAKE_BINARY_DIR}/.deps
+      GIT_REPOSITORY https://github.com/openairinterface/o-du-phy.git
+      GIT_TAG ${K_VERSION}
+      CONFIGURE_COMMAND ""  # nothing to configure
+      BUILD_COMMAND cd fhi_lib/lib && WIRELESS_SDK_TOOLCHAIN=gcc RTE_SDK=${dpdk_PREFIX} XRAN_DIR=.. make XRAN_LIB_SO=1
+      BUILD_IN_SOURCE ON
+      INSTALL_COMMAND ""
+      BUILD_BYPRODUCTS ${xran_DIR}/build/libxran.so
+  )
+  add_library(xran::xran UNKNOWN IMPORTED)
+  add_dependencies(xran::xran extern_xran)
+  # This is a workaround for the fact that included directories of an imported
+  # target should exist in the filesystem already at the configuration time.
+  # ref: https://gitlab.kitware.com/cmake/cmake/-/issues/15052
+  file(MAKE_DIRECTORY "${xran_DIR}/api/")
+  file(MAKE_DIRECTORY "${xran_DIR}/build/")
+  set_target_properties(xran::xran PROPERTIES
+    IMPORTED_LOCATION "${xran_DIR}/build/libxran.so"
+    INTERFACE_INCLUDE_DIRECTORIES "${xran_DIR}/api/"
+  )
+  message(STATUS "xran not found. Will clone and build automatically K release ${K_VERSION}")
   target_compile_definitions(oran_fhlib_5g PRIVATE K_RELEASE)
 else()
-  message(FATAL_ERROR "Found xran version ${xran_VERSION} but needed ${F_VERSION} (F release) or ${K_VERSION} (K release)")
+  message(FATAL_ERROR "could not find xran, and auto-download disabled. Update
+  xran_LOCATION, or set -Dxran_DOWNLOAD=ON")
 endif()
 
 # Ignore xran-specific warning: we don't care/can't change the following warning, so suppress