2025-02-10: v9.0.6: Example vendor layer plug-in

Added
- Example vendor layer plug-in and documentation (in quick start guide)

CHANGELOG.md

@@ -1,5 +1,9 @@
 # OB-USP-AGENT Changelog since Release 9.0.0
 
+## 2025-02-10 v9.0.6
+### Added
+- Example vendor layer plug-in and documentation (in quick start guide)
+
 ## 2025-01-13 v9.0.5
 ### Fixed
 - Compilation failure when building for pure USP Service

QUICK_START_GUIDE.md

@@ -453,6 +453,34 @@ int RefreshIPInterfaceInstances(int group_id, char *path, int *expiry_period)
     *expiry_period = 30;
     return USP_ERR_OK;
 }
+```
 
+## Extending the data model using plug-ins
+As an alternative (or in addition) to extending the data model by adding source code to the stub functions in `src/vendor/vendor.c`, the data model may also be extended using plug-ins. These are shared objects which are dynamically loaded by OB-USP-AGENT at runtime.
+
+Plug-ins are particularly useful in the following cases:
+* When you would like to separate out parts of the extended data model into different binaries e.g., `Device.WiFi` can be implemented in a separate shared object from `Device.USB`. The source code for each of these data model trees may be stored in different repositories and compiled separately.
+* When creating USP Services on memory constrained devices. The OB-USP_AGENT executable may be shared by each USP Service and the USP Broker. Specialization of the data model may be provided by separate plug-ins for each USP Service and the USP Broker.
+
+Plug-ins must provide the three functions `VENDOR_Init()`, `VENDOR_Start()` and `VENDOR_Stop()`, written in the same way as described earlier.
+
+### Example plug-in
+An example plug-in is contained in the `/examples/plugin` directory. The example registers a single data model parameter (`Device.Day`), providing a different day of the week each time it is read. To build it, use the following:
 
 ```
+$ cd obuspa/examples/plugin
+$ autoreconf --force --install
+$ ./configure
+$ make
+$ sudo make install
+```
+
+A shared object will be created in `obuspa/examples/plugin/.libs/plugin.so` and installed to (typically) `/usr/local/lib/plugin/plugin.so`. To invoke OB-USP-AGENT with the plug-in use the '-x' option:
+
+```
+cd obuspa
+obuspa -p -v 4 -r factory_reset_example.txt -i eth0 -x examples/plugin/.libs/plugin.so
+```
+ OB-USP-AGENT supports the loading of multiple plug-ins at start-up, each one specified using a '-x' command line switch.
+
+

examples/plugin/Makefile.am

@@ -0,0 +1,16 @@
+AM_CPPFLAGS = -I$(top_srcdir)/../../src/include \
+              -I$(top_srcdir)/../../src/core \
+              -I$(top_srcdir)/../../src/vendor
+AM_CFLAGS = -Wall -Wfatal-errors
+
+pkglib_LTLIBRARIES = plugin.la
+plugin_la_SOURCES = vendor_plugin.c
+plugin_la_CPPFLAGS = $(openssl_CFLAGS)
+plugin_la_CPPFLAGS += $(AM_CPPFLAGS) \
+                      -Werror \
+                      -Werror=unused-value \
+                      -Werror=format \
+                      -Winit-self \
+                      -Wparentheses -Werror=parentheses \
+                      -Wuninitialized -Werror=uninitialized -Werror=maybe-uninitialized -Wpointer-arith
+plugin_la_LDFLAGS = -avoid-version -module -shared -export-dynamic

examples/plugin/configure.ac

@@ -0,0 +1,39 @@
+# -*- Autoconf -*-
+# Process this file with autoconf to produce a configure script.
+
+AC_PREREQ([2.63])
+AC_INIT([plugin],[0.0.1])
+AM_INIT_AUTOMAKE([foreign silent-rules subdir-objects -Wall -Werror -Wno-portability])
+AC_CONFIG_MACRO_DIR([./m4])
+LT_PREREQ([2.2])
+
+# Define _GNU_SOURCE if using GNU versions of strerror_r and dladdr()
+AC_USE_SYSTEM_EXTENSIONS
+
+# Configure use of libtool
+LT_INIT([shared disable-static])
+
+# Checks for programs.
+AC_PROG_CC
+AM_PROG_CC_C_O
+
+# Find out if GNU or XSI versions of strerror_r are being used
+AC_FUNC_STRERROR_R
+
+# Check for glibc specific functionality, setting HAVE_MALLINFO and HAVE_EXECINFO_H defines in the generated makefiles
+AC_CHECK_HEADERS([malloc.h])
+AC_CHECK_HEADERS([execinfo.h])
+AC_CHECK_FUNCS([mallinfo])
+AC_CHECK_FUNCS([mallinfo2])
+
+# Needed to work with default vendor_defs.h (USP Broker and USP Service functionalities need UDS MTP)
+AC_DEFINE(ENABLE_UDS)
+
+# Needed to get include path for OpenSSL headers
+PKG_CHECK_MODULES([openssl], [openssl])
+
+# Generate Makefiles
+AC_CONFIG_FILES([Makefile])
+
+# Finally, generate top-level config.status.
+AC_OUTPUT

examples/plugin/vendor_plugin.c

@@ -0,0 +1,130 @@
+/*
+ *
+ * Copyright (C) 2025, Broadband Forum
+ * Copyright (C) 2025  Vantiva Technologies, SAS
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * 3. Neither the name of the copyright holder nor the names of its
+ *    contributors may be used to endorse or promote products derived from
+ *    this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ * THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ */
+
+/**
+ * \file vendor_plugin.c
+ *
+ * Implements the interface to all vendor implemented data model nodes
+ *
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <stdbool.h>
+#include <string.h>
+
+#include "usp_err_codes.h"
+#include "vendor_defs.h"
+#include "vendor_api.h"
+#include "usp_api.h"
+
+//-------------------------------------------------------------------------
+// Forward references
+int Get_PluginDay(dm_req_t *req, char *buf, int len);
+
+/*********************************************************************//**
+**
+** VENDOR_Init
+**
+** Initialises this component, and registers all parameters and vendor hooks, which it implements
+**
+** \param   None
+**
+** \return  USP_ERR_OK if successful
+**
+**************************************************************************/
+int VENDOR_Init(void)
+{
+    // Register a parameter which this plugin provides
+    return USP_REGISTER_VendorParam_ReadOnly("Device.Day", Get_PluginDay, DM_STRING);
+}
+
+/*********************************************************************//**
+**
+** VENDOR_Start
+**
+** Called after data model has been registered and after instance numbers have been read from the USP database
+** Typically this function is used to seed the data model with instance numbers or
+** initialise internal data structures which require the data model to be running to access parameters
+**
+** \param   None
+**
+** \return  USP_ERR_OK if successful
+**
+**************************************************************************/
+int VENDOR_Start(void)
+{
+    return USP_ERR_OK;
+}
+
+/*********************************************************************//**
+**
+** VENDOR_Stop
+**
+** Called when stopping USP agent gracefully, to free up memory and shutdown
+** any vendor processes etc
+**
+** \param   None
+**
+** \return  USP_ERR_OK if successful
+**
+**************************************************************************/
+int VENDOR_Stop(void)
+{
+    return USP_ERR_OK;
+}
+
+/*********************************************************************//**
+**
+** Get_PluginDay
+**
+** Gets the value of Device.Plugin.Day
+**
+** \param   req - pointer to structure identifying the path
+** \param   buf - pointer to buffer into which to return the value of the parameter (as a textual string)
+** \param   len - length of buffer in which to return the value of the parameter
+**
+** \return  USP_ERR_OK if successful
+**
+**************************************************************************/
+int Get_PluginDay(dm_req_t *req, char *buf, int len)
+{
+    static int count = 0;
+    static const char *days[7] = { "Mon", "Tues", "Wed", "Thurs", "Fri", "Sat", "Sun" };
+    
+    strncpy(buf, days[count], len);
+    count = (count + 1) % 7;
+
+    return USP_ERR_OK;
+}

src/core/version.h

@@ -40,4 +40,4 @@
  */
 
  /* Lines below main version may include patch version numbers */
-#define AGENT_SOFTWARE_VERSION  "9.0.5"
+#define AGENT_SOFTWARE_VERSION  "9.0.6"