Merge pull request #10 from CloudlyIO/release/1.1.0

release 1.1.0 -- modular libhalmplane

README.md

@@ -12,9 +12,15 @@ Open Fronthaul Interface specified by O-RAN Workgroup 4.
   the implementation in `fb-oru`.
 * **mplane_client** - M-Plane client implementation.
 * **climp** - A command-line interface utility for M-Plane operations.
-* **fb-oru** - Code for the operating system and applications of an O-RU. This
-  includes the legacy implementation of the M-Plane server, which has most of
-  its code contained in `fb-oru/yang-manager-server`.
+
+## Client and Server Configuration Workflow
+* Follow the [meta-mplane](https://github.com/lf-connectivity/open-mplane/tree/main/meta-mplane)
+  setup guide to build and run the mplane_server
+* Build the [mplane_client](https://github.com/lf-connectivity/open-mplane/tree/main/mplane_client)
+  on your host or using Docker
+* Use the [mpclient-demo](https://github.com/lf-connectivity/open-mplane/tree/main/mplane_client/example)
+  or the [M-Plane Demo](https://github.com/lf-connectivity/open-mplane/tree/main/mplane_client/example/demo)
+  to connect and communicate with the server
 
 ## License
 Open M-Plane is MIT licensed, as found in the LICENSE file.

libhalmplane/CMakeLists.txt

@@ -38,8 +38,8 @@ elseif( "${CONTEXT}" STREQUAL "YOCTO")
   endif()
 
   set(LIBRARY_NAME halmplane)
-  set(version "0.1")
-  project (halmplane VERSION 0.1.0 LANGUAGES CXX)
+  set(version "1.1")
+  project (halmplane VERSION 1.1.0 LANGUAGES CXX)
   add_library(${LIBRARY_NAME} SHARED)
   set_target_properties(${LIBRARY_NAME} PROPERTIES VERSION ${PROJECT_VERSION})
   set_target_properties(${LIBRARY_NAME} PROPERTIES SOVERSION ${PROJECT_VERSION_MAJOR})
@@ -54,10 +54,8 @@ elseif( "${CONTEXT}" STREQUAL "YOCTO")
   endif()
 
   if (NOT GITDIR)
-
     get_filename_component (GITDIR ${PROJECT_SOURCE_DIR} DIRECTORY)
     list(APPEND CMAKE_MODULE_PATH ${GITDIR}/buildTools/cmake/Modules)
-
   endif()
 
   include_directories(
@@ -69,8 +67,12 @@ elseif( "${CONTEXT}" STREQUAL "YOCTO")
   include(${BOARD}/CMakeLists.txt)
   target_include_directories(halmplane PUBLIC hal-common/inc)
   target_include_directories(halmplane PUBLIC inc)
-  install(
-    FILES
+
+  if(${BUILD_BOARD_STYLE} STREQUAL "MODULE")
+    set_target_properties(${LIBRARY_NAME} PROPERTIES OUTPUT_NAME ${LIBRARY_NAME}-mod-${BOARD})
+  else()
+    install(
+      FILES
       inc/MplaneAlarms.h
       inc/MplaneAntennaCalibration.h
       inc/MplaneBeamforming.h
@@ -92,8 +94,9 @@ elseif( "${CONTEXT}" STREQUAL "YOCTO")
       inc/MplaneFan.h
       inc/MplaneSync.h
       inc/HalMplane.h
-    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
-  )
+      DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+    )
+  endif()
 
   install(TARGETS halmplane
     LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}

libhalmplane/README.md

@@ -27,3 +27,5 @@ shared library is generated and may be installed on a host system with the
 `make install/$TARGET` Makefile target.
 
 *libhalmplane* is also incorporated into the `yang-manager-server` build.
+
+See `modular/README.md` for a detailed explanation of using the `modular` board type.

libhalmplane/example/CMakeLists.txt

@@ -6,9 +6,5 @@ string(CONCAT SRC
 )
 include_directories(inc)
 
-if( "${CONTEXT}" STREQUAL "YOCTO")
-  list(TRANSFORM SRC PREPEND "example/")
-  target_sources(halmplane PRIVATE ${SRC})
-else()
-  add_sources(SOURCES ${SRC})
-endif()
+list(TRANSFORM SRC PREPEND "example/")
+target_sources(halmplane PRIVATE ${SRC})

libhalmplane/example/src/HalMplane.cpp

@@ -5,9 +5,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+#include <map>
+#include "libtinyxml2/tinyxml2.h"
 #include "HalMplane.h"
+#include "MplaneInterfaces.h"
+#include "MplaneProcessingElements.h"
+#include "MplaneUplaneConf.h"
 
-int halmplane_init()
+using namespace tinyxml2;
+
+int halmplane_init(tinyxml2::XMLDocument* doc)
 {
     return 0;
 }
@@ -16,3 +23,81 @@ int halmplane_exit()
 {
     return 0;
 }
+
+typedef struct
+{
+  const char* key;
+  void* ptr;
+} labeled_ptr_t;
+
+static labeled_ptr_t api_functions[] = {
+  // HalMplane.h
+  {"int halmplane_init(XMLDocument*)",
+   (void*)(int (*)(XMLDocument*)) halmplane_init},
+  {"int halmplane_exit()",
+   (void*)(int (*)()) halmplane_exit},
+
+  // MplaneInterfaces.h
+  {"halmplane_error_t halmplane_interface_update(interface_t*)",
+   (void*)(halmplane_error_t (*)(interface_t*)) halmplane_interface_update},
+  {"halmplane_error_t halmplane_interface_update_description(const char*, const char*)",
+   (void*)(halmplane_error_t (*)(const char*, const char*)) halmplane_interface_update_description},
+  {"halmplane_error_t halmplane_interface_update_type(const char*, const char*)",
+   (void*)(halmplane_error_t (*)(const char*, const char*)) halmplane_interface_update_type},
+  {"halmplane_error_t halmplane_interface_update_enabled(const char*, bool)",
+   (void*)(halmplane_error_t (*)(const char*, bool)) halmplane_interface_update_enabled},
+  {"halmplane_error_t halmplane_interface_update_l2_mtu(const char*, int)",
+   (void*)(halmplane_error_t (*)(const char*, int)) halmplane_interface_update_l2_mtu},
+  {"halmplane_error_t halmplane_interface_update_vlan_tagging(const char*, bool)",
+   (void*)(halmplane_error_t (*)(const char*, bool)) halmplane_interface_update_vlan_tagging},
+  {"halmplane_error_t halmplane_interface_update_base_interface(const char*, const char*)",
+   (void*)(halmplane_error_t (*)(const char*, const char*)) halmplane_interface_update_base_interface},
+  {"halmplane_error_t halmplane_interface_update_vlan_id(const char*, int)",
+   (void*)(halmplane_error_t (*)(const char*, int)) halmplane_interface_update_vlan_id},
+  {"halmplane_error_t halmplane_interface_update_mac_address(const char*, const char*)",
+   (void*)(halmplane_error_t (*)(const char*, const char*)) halmplane_interface_update_mac_address},
+
+  // MplaneProcessingElements.h
+  {"halmplane_error_t halmplane_update_ru_element(ru_elements_t*)",
+   (void*)(halmplane_error_t (*)(ru_elements_t*)) halmplane_update_ru_element},
+
+  // MplaneUplaneConf.h
+  {"int halmplane_setUPlaneConfiguration(user_plane_configuration_t*)",
+   (void*)(int (*)(user_plane_configuration_t*)) halmplane_setUPlaneConfiguration},
+  {"int halmplane_update_rx_eaxc(const char*, e_axcid_t*)",
+   (void*)(int (*)(const char*, e_axcid_t*)) halmplane_update_rx_eaxc},
+  {"int halmplane_update_tx_eaxc(const char*, e_axcid_t*)",
+   (void*)(int (*)(const char*, e_axcid_t*)) halmplane_update_tx_eaxc},
+  {"int halmplane_update_rx_endpoint_compression(const char*, compression_t*)",
+   (void*)(int (*)(const char*, compression_t*)) halmplane_update_rx_endpoint_compression},
+  {"int halmplane_update_tx_endpoint_compression(const char*, compression_t*)",
+   (void*) (int (*)(const char*, compression_t*)) halmplane_update_tx_endpoint_compression},
+  {"int halmplane_update_rx_endpoint_compression_dyn_config(const char*, dynamic_compression_configuration_t*)",
+   (void*)(int (*)(const char*, dynamic_compression_configuration_t*)) halmplane_update_rx_endpoint_compression_dyn_config},
+  {"int halmplane_update_tx_endpoint_compression_dyn_config(const char*, dynamic_compression_configuration_t*)",
+   (void*) (int (*)(const char*, dynamic_compression_configuration_t*)) halmplane_update_tx_endpoint_compression_dyn_config},
+  {"int halmplane_register_rx_carrier_state_cb(halmplane_carrier_state_cb_t)",
+   (void*)(int (*)(halmplane_carrier_state_cb_t)) halmplane_register_rx_carrier_state_cb},
+  {"int halmplane_register_tx_carrier_state_cb(halmplane_carrier_state_cb_t)",
+   (void*)(int (*)(halmplane_carrier_state_cb_t)) halmplane_register_tx_carrier_state_cb},
+
+  {NULL, NULL}
+};
+
+
+extern "C"
+{
+  void *function_map()
+  {
+    std::map<std::string, void*> *registered_functions;
+    registered_functions = new std::map<std::string, void*>();
+
+    int i = 0;
+    while(api_functions[i].key != NULL)
+      {
+	(*registered_functions)[api_functions[i].key] = api_functions[i].ptr;
+	i++;
+      }
+    return registered_functions;
+  }
+}

libhalmplane/hal-common/CMakeLists.txt

@@ -1,6 +1,6 @@
 include_directories(inc)
 
-if( "${CONTEXT}" STREQUAL "YOCTO")
+if(("${CONTEXT}" STREQUAL "YOCTO") OR ("${CONTEXT}" STREQUAL "MODULE"))
   if( "${BOARD}" STREQUAL "zcu111")
     string(CONCAT SRC
       "hal-common/fb-oru/FbOruPerformanceMgmt.cpp;"

libhalmplane/inc/HalMplane.h

@@ -7,16 +7,19 @@
 
 #ifndef __HAL_MPLANE_H__
 #define __HAL_MPLANE_H__
+#include "libtinyxml2/tinyxml2.h"
 
 /**
- * @brief HAl init function, to be called before YANG handlers initialization.
+ * @brief HAL init function, to be called before YANG handlers initialization.
+ *
+ * doc is a pointer to an xml config object if any board needs to preset runtime parameters
  *
  * @return 0 if successful, 1 otherwise
  */
-int halmplane_init();
+int halmplane_init(tinyxml2::XMLDocument* doc);
 
 /**
- * @brief HAl exit function, to be called when application exits.
+ * @brief HAL exit function, to be called when application exits.
  *
  * @return 0 if successful, 1 otherwise
  */

libhalmplane/inc/MplaneAntennaCalibration.h

@@ -53,6 +53,6 @@ typedef struct antenna_calibration_data_s {
  * @ingroup AntennaCalibrationFunctions
  */
 halmplane_error_t halmplane_start_antenna_calibration(
-    const* antenna_calibration_data_t);
+    const antenna_calibration_data_t*);
 
 #endif // __MPLANE_ANTENNA_CALIBRATION_H__

libhalmplane/inc/MplaneFan.h

@@ -13,7 +13,7 @@
 #include <unistd.h>
 
 #include "MplaneTypes.h"
-#include "smbus.h"
+
 
 /** @struct fan_state_s
  * @brief Struct representing a fan on the O-RU.

libhalmplane/inc/MplanePerformanceMgmt.h

@@ -286,6 +286,4 @@ typedef void (*halmplane_epe_meas_cb_t)(
 int halmplane_activateEpeMeasObjects(
     struct epe_measurement_objects_t config, halmplane_epe_meas_cb_t cb);
 
-#endif
-
 #endif // __MPLANE_PERFORMANCE_MGMT_H__

libhalmplane/inc/MplaneSync.h

@@ -45,7 +45,7 @@ typedef struct ptp_config_s {
   uint8_t* accepted_block_classes;
   ptp_profile_t ptp_profile;
   struct {
-    multi_cast_mac_address_t multicast_mac_address;
+    multicast_mac_address_t multicast_mac_address;
     int16_t delay_asymmetry;
   } g_8275_1_config;
   struct {
@@ -125,7 +125,7 @@ typedef struct synce_status_s {
   } sources;
 } synce_status_t;
 
-/** @struct gnass_config_s
+/** @struct gnss_config_s
  *  @brief GNSS Configuration
  */
 typedef struct gnss_config_s {
@@ -141,10 +141,10 @@ typedef struct gnss_state_s {
   char* name;
   enum {
     SYNCHRONIZED,
-    ACQUIRING - SYNC,
-    ANTENNA - DISCONNECTED,
+    ACQUIRING_SYNC,
+    ANTENNA_DISCONNECTED,
     BOOTING,
-    ANTENNA - SHORT - CIRCUIT
+    ANTENNA_SHORT_CIRCUIT
   } gnss_sync_status;
   struct {
     uint8_t satellites_tracked;

libhalmplane/inc/MplaneTransceiver.h

@@ -7,6 +7,7 @@
 
 #ifndef __MPLANE_TRANSCEIVER_H__
 #define __MPLANE_TRANSCEIVER_H__
+#include <stdint.h>
 
 typedef struct leafref_s {
   char* path;

libhalmplane/modular/CMakeLists.txt

@@ -0,0 +1,37 @@
+
+find_library(TINYXML2 tinyxml2)
+find_library(DL dl)
+
+target_link_libraries(halmplane
+  ${DL}
+  ${TINYXML2}
+)
+
+string(CONCAT SRC
+
+  "src/HalMplane.cpp;"
+  "src/ModuleLoader.cpp;"
+  "src/MplaneAlarms.cpp;"
+  "src/MplaneAld.cpp;"
+  "src/MplaneAntennaCalibration.cpp;"
+  "src/MplaneBeamforming.cpp;"
+  "src/MplaneDelayMgmt.cpp;"
+  "src/MplaneEcpri.cpp;"
+  "src/MplaneExternalio.cpp;"
+  "src/MplaneFan.cpp;"
+  "src/MplaneHardware.cpp;"
+  "src/MplaneInterfaces.cpp;"
+  "src/MplaneModuleCapability.cpp;"
+#####  "src/MplanePerformanceMgmt.cpp;"
+  "src/MplaneProcessingElements.cpp;"
+  "src/MplaneSupervision.cpp;"
+  "src/MplaneSync.cpp;"
+  "src/MplaneTransceiver.cpp;"
+  "src/MplaneUplaneConf.cpp;"
+
+)
+include_directories("modular/inc")
+
+list(TRANSFORM SRC PREPEND "modular/")
+target_sources(halmplane PRIVATE ${SRC})
+

libhalmplane/modular/README.md

@@ -0,0 +1,45 @@
+# *libhalmplane* `modular` Board
+
+This board will allow selecting the halmplane driver for any other compatible
+board by specifying the filename of its shared library in the server configuration.
+
+## Building
+`mplane_server` must be build with BUILD_BOARD=modular
+
+```
+BUILD_BOARD=modular BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE BUILD_BOARD" bitbake mplane-image-x86
+```
+
+To rebuild with a different builtin board type it may be necessary to rebuild that explicitly
+to invalidate the build hash even though the source files have not changed.
+```
+BUILD_BOARD=example BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE BUILD_BOARD" bitbake -C configure halmplane
+```
+
+To select a module in config file, edit `/usr/share/mplane-server/YangConfig.xml`
+in the `<halmplane-board-modular>` element.
+
+To build a specific module
+```
+BUILD_BOARD=example BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE BUILD_BOARD" bitbake -C configure halmplanemodule
+```
+
+Each module has by default a filename of the form `libhalmplane-mod-<BUILD_BOARD>.so` with symlinks
+generated that reflect the version. This will allow parallel installation of multiple modules without
+packaging conflicts.
+
+The current bitbake recipes do not support automatically installing the resulting module into the
+project `rootfs`, so a command similar to
+```
+cp ./tmp/work/core2-64-poky-linux/halmplanemodule/1.1-r0/image/usr/lib/libhalmplane-mod-example.so.1.1.0 ./tmp/work/mplanex86-poky-linux/mplane-image-x86/1.0-r0/rootfs/usr/lib/
+```
+can achieve the desired outcome manually.
+
+
+## Enabling a board for use as a module
+To operate as a module, the only thing needed is to provide a function with prototype
+```
+void *function_map();
+```
+that is also `extern "C"`. Sample code can be found in `example/src/HalMplane.cpp`
+and a complete list of supported API endpoints can be found in `modular/src/HalMplane.cpp`.

libhalmplane/modular/inc/ModuleLoader.h

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) Linux Foundation and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#ifndef __MODULE_LOADER_H__
+#define __MODULE_LOADER_H__
+
+#include <cstddef>
+#include <map>
+#include <string>
+#include <dlfcn.h>
+
+
+class ModuleLoader
+{
+private:
+  const char* libname;
+  void* dlhandle;
+  std::map<std::string, void*> *registered_functions;
+
+public:
+  ModuleLoader();
+  void open(const char* libname);
+  void* get(const char* ftag);
+};
+
+
+ModuleLoader* _loader();
+
+
+#endif