[Minios-devel] [UNIKRAFT PATCH v3 8/8] lib/uklibparam: Add documentation for parameters

[Sharan Santhanam <sharan.santhanam@xxxxxxxxx>]

This patch adds documentation for Unikraft library argument
library. The patch adds help text to configure the heap size argument
in the linuxu platform.

Signed-off-by: Sharan Santhanam <sharan.santhanam@xxxxxxxxx>
---
 doc/guides/developers-app.rst | 107 ++++++++++++++++++++++++++++++++++
 plat/linuxu/Config.uk         |   6 +-
 2 files changed, 111 insertions(+), 2 deletions(-)

diff --git a/doc/guides/developers-app.rst b/doc/guides/developers-app.rst
index 29db81d7..26a57a54 100644
--- a/doc/guides/developers-app.rst
+++ b/doc/guides/developers-app.rst
@@ -367,6 +367,113 @@ syscall``. Namely: ::
   general, a 0 return value indicates success.  A -1 return value
   indicates an error, and an error code is stored in errno.
 
+==================================
+Command line arguments in Unikraft
+==================================
+A library within Unikraft may need to be configured while deploying it with an
+application or the default value of a configuration option may vary based on
+the application use case. It is necessary to overwrite this value at the time
+an application is run. The command line arguments provided by a user shall be
+used to overwrite the default configuration values. Thus a Unikraft command 
line
+arguments could either belong to an application or to a library. These two
+classes of argument are separated by ``--``;. The arguments for a Unikraft
+library precedes the ``--``, followed by the application arguments.
+
+Type of parameters in a library
+--------------------------------
+Unikraft provides support to pass arguments of the following data type:
+
+========  ========================
+Type      Description
+========  ========================
+char      Single character value and it is an alias for __s8.
+__s8      Same as char
+__u8      Single byte value
+__s16     Short signed integer
+__u16     Short unsigned integer
+int       Integer and it is an alias for __s32.
+__s32     Signed integer
+__u32     Unsigned integer
+__s64     Signed long integer
+__u64     Unsigned long integer
+charp     C strings.
+========  ========================
+
+Register a library parameter to Unikraft
+-----------------------------------------
+In order for a library to configure options at execution time, the library 
needs
+to select the library `uklibparam` while configuring the Unikraft build.
+The library should also be registered  with the `uklibparam` library using 
+`addlib_paramprefix` in the Makefile.uk of your library.
+
+There are three interfaces through which a library registers a variable as a
+parameter that maybe altered while executing an application. These are:
+
+* UK_LIB_PARAM     - Pass a scalar value of the above type to a variable.
+* UK_LIB_PARAM_STR - Pass a null terminated string to a variable.
+* UK_LIB_PARAM_ARR - Pass space separated list of values of the above type.
+
+Each library parameter is identified by the following format ::
+
+ [library name].[variable name]
+
+ where,
+     library name is the name registered with Unikraft build system.
+     variable name is the name of the global or static variable in the program.
+
+Examples
+--------
+If the library needs to configure variable at execution time, it needs some
+configuration to be performed while building the library. A Unikraft library 
can
+be specific to a particular platform or common across all the platform.
+For the common library, one has to edit the Makefile.uk with
+
+.. code-block:: bash
+
+ $(eval $(call addlib_paramprefix,libukalloc,alloc))
+ where,
+      libukalloc is the name of the library
+      alloc is the alias for the library name.
+
+As the next step, we define a variable and register it with the `uk_libparam`
+library. The example below a simple code snippet.
+
+.. code-block:: c
+
+    static __u32 heap_size = CONFIG_LINUXU_DEFAULT_HEAPMB;
+    UK_LIB_PARAM(heap_size, __u32);
+
+We can override the default value using the following command line
+
+.. code-block:: bash
+
+  ./unikraft_linuxu-x86_64 linuxu.heap_size=10 --
+
+We demonstrate a examples for parameters that are defined as string. We define 
a char pointer pointing to a default value and register it with the 
`uk_libparam` library using the UK_LIB_PARAM_STR helper function. The code 
snippet below demonstrate this.
+
+.. code-block:: c
+
+    static const char \*test_string = "Hello World";
+    UK_LIB_PARAM_STR(test_string);
+
+We can override the default value using the following command
+
+.. code-block:: bash
+
+  ./unikraft_linuxu-x86_64 linuxu.test_string="Hello Unikraft!" --
+
+The example below demonstrate a scheme to pass list of scalar datatype as a 
parameter to a library. As in the previous example, we define an array variable 
and register it with the `uk_libparam` library using the UK_LIB_PARAM_ARR 
helper function.
+
+.. code-block:: c
+
+    static int test_array[5] = {0};
+    UK_LIB_PARAM_ARR(test_array, int);
+
+The element in an array are delimited by ' '. The following command 
demonstrate the way to overwrite the default element in an array.
+
+.. code-block:: bash
+
+  ./unikraft_linuxu-x86_64 linuxu.test_array="1 2 3 4 5" --
 
 ============================
 Make Targets
diff --git a/plat/linuxu/Config.uk b/plat/linuxu/Config.uk
index 132758eb..ede9589a 100644
--- a/plat/linuxu/Config.uk
+++ b/plat/linuxu/Config.uk
@@ -12,6 +12,8 @@ if (PLAT_LINUXU)
        int "Default heap size (MB)"
        default 4
        help
-               Default size of heap memory to be allocated when no
-               '-m' parameter was given to the linuxu executable
+               Default size of heap memory to be allocated. The heap size may 
also be
+               changed by using linuxu.heap_size as a command line argument. 
For more
+               information refer to "Command line arguments in Unikraft" 
sections in 
+               the developers guide
 endif
-- 
2.20.1


_______________________________________________
Minios-devel mailing list
Minios-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/minios-devel