Merge branch 'develop' into feature-127-protocol-split

common/utils/DOC/loader/devusage/api.md

@@ -0,0 +1,20 @@
+ Loader API is defined in the [common/utils/load_module_shlib.h](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/common/utils/load_module_shlib.h) include file.
+```c
+int load_module_shlib(char *modname,loader_shlibfunc_t *farray, int numf)
+```
+* possibly initializes the loader, if it has not been already initialized
+* Formats the full shared library path, using the `modname` argument and the loader `shlibpath` and `shlibversion`configuration parameters.
+* loads the shared library, using the dlopen system call
+* looks for `< modname >_autoinit` symbol, using the `dlsym` system call and possibly call the corresponding function.
+* looks for `< modname >_checkbuildver` symbol, using the `dlsym` system call and possibly calls the corresponding function. If the return value of this call is `-1`, program execution is stopped. It is the responsibility of the shared library developer to implement or not a `< modname >_checkbuildver` function and to decide if a version mismatch is a fatal condition. The `< modname >_checkbuildver` function must match the `checkverfunc_t` function type. The first argument is the main executable version, as set  in the `PACKAGE_VERSION` macro defined in the [oai CMakeLists](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/cmake_targets/CMakeLists.txt#L218), around line 218. The second argument points to the shared library version which should be set  by the `< modname >_checkbuildver` function.
+* If the farray pointer is null,  looks for `< modname >_getfarray` symbol, calls the corresponding function when the symbol is found. `< modname >_getfarray` takes one argument, a pointer to a  `loader_shlibfunc_t` array, and returns the number of items in this array, as defined by the `getfarrayfunc_t` type. The `loader_shlibfunc_t` array returned by the shared library must be fully filled (both `fname` and `fptr` fields).
+* looks for the `numf` function symbols listed in the `farray[i].fname` arguments and set the corresponding `farray[i].fptr`function pointers
+
+
+```c
+void * get_shlibmodule_fptr(char *modname, char *fname)
+```
+Returns a pointer to the symbol `fname`, defined in module `modname`, or `NULL` if the symbol is not found.
+
+[loader home page](../../loader.md)
+[loader developer home page](../devusage.md)

common/utils/DOC/loader/devusage/loading.md

@@ -0,0 +1,56 @@
+Implementing a shared library dynamic load using the oai loader  is a two steps task:
+1.  define the `loader_shlibfunc_t` array, describing the list of externally available functions implemented in the library. This is the interface of the module.
+1.  Call the `load_module_shlib` function, passing it the previously defined array and the number of items in this array. The first argument to `load_module_shlib` is the name identifying the module, which is also used to format the corresponding library name, as described [here](loader/rtusage#shared-library-names)
+
+After a successful `load__module_shlib` call, the function pointer of each `loader_shlibfunc_t` array item has been set and can be used to call the corresponding function.
+
+Typical loader usage looks like:
+
+```c
+/* shared library loader include file */
+#include "common/utils/load_module_shlib.h"
+.............
+/*
+  define and initialize the array, describing the list of functions
+  implemented in "mymodule"
+*/
+  loader_shlibfunc_t mymodule_fdesc[2];
+  mymodule_fdesc[0].fname="mymodule_f1";
+  mymodule_fdesc[1].fname="mymodule_f2";
+
+/*
+ load the library, it's name must be libmymod.so. Configuration can be
+ used to specify a specific path to look for libmymod.so. Configuration
+ can also specify a version, for example "V1", in this case the loader
+ will look for libmymodV1.so
+*/
+  ret=load_module_shlib("mymod",mymodule_fdesc, sizeof(mymodule_fdesc)/sizeof(loader_shlibfunc_t));
+  if (ret < 0) {
+       fprintf(stderr,"Library couldn't be loaded\n");
+  } else {
+/*
+library has been loaded, we probably want to call some functions...
+*/
+  ret=((funcf1_t)mymodule_fdesc[0].fptr)();
+
+..................
+/*
+later and/or somewhere else in the code you may want to call function "mymodule_f2"
+You can use the loader get_shlibmodule_fptr(char *modname, char *fname) function
+to retrieve the pointer to that function
+*/
+funcf2_t *f2;
+int ret;
+int intarg1;
+char *strarg;
+........................
+f2 = (funcf2_t)get_shlibmodule_fptr("mymodule", "mymodule_f2")
+if (f2 != NULL) {
+  ret = f2(intarg1,strarg);
+}
+...............
+```
+When loading a shared library the loader looks for a symbol named `< module name > _autoinit` and, if it finds it, calls it. The `autoinit` function is called without any argument and the returned value, if any, is not tested.
+
+[loader home page](../loader.md)
+[loader developer home page](../../loader/devusage.md)

common/utils/DOC/loader/devusage/struct.md

@@ -0,0 +1,10 @@
+# `loader_shlibfunc_t`structure
+It is defined in include file [ common/util/load_module_shlib.h ](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/common/utils/load_module_shlib.h#L38). This structure is used  to list the symbols that should be searched by the loader when calling the `load_module_shlib` function.
+
+| Fields     | Description                                                       | I/O |
+|:-----------|:------------------------------------------------------------------|----:|
+| `fname`    | symbol name, is passed to the [`dlsym`](http://man7.org/linux/man-pages/man3/dlsym.3.html) system call performed by the loader to get a pointer to the symbol | I |
+| `fptr`     | pointer to the symbol name, set by the loader. `fptr` is defined as a `int (*fptr)(void)` function type | O |
+
+[loader home page](../../loader.md)
+[loader developer home page](../devusage.md)