|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] Re: [Minios-devel] [UNIKRAFT PATCH v3 8/8] lib/uklibparam: Add documentation for parameters
Hi Sharan, this patch looks good. I might fix a few minor grammatical errors in
the documentation on upstream.
-- Felipe
Reviewed-by: Felipe Huici <felipe.huici@xxxxxxxxx>
On 21.08.19, 17:54, "Sharan Santhanam" <Sharan.Santhanam@xxxxxxxxx> wrote:
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
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |