|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] Re: [Minios-devel] [UNIKRAFT PATCH v2 7/7] lib/uklibparam: Add documentation for parameters
Hi Sharan,
Please see my comment inline.
-- Felipe
On 13.08.19, 14:37, "Minios-devel on behalf of Sharan Santhanam"
<minios-devel-bounces@xxxxxxxxxxxxxxxxxxxx on behalf of
Sharan.Santhanam@xxxxxxxxx> wrote:
This patch adds documentation for Unikraft library argument
library.
Signed-off-by: Sharan Santhanam <sharan.santhanam@xxxxxxxxx>
---
doc/guides/developers-app.rst | 107 ++++++++++++++++++++++++++++++++++
1 file changed, 107 insertions(+)
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.
While this is clear enough, from a user perspective figuring out what the
values for library name and variable name isn't. Right now, the only way they
have of finding this out is looking at the actual code or grepping for call
addlib_paramprefix and UK_LIB_PARAM, not particularly user-friendly.
I wonder whether it wouldn't be better to populate this information in the
kConfig menu, and update this documentation to reflect this (e.g., in linuxu's
heap size option, note that the size can be modified by adding
linuxu.heap_size=x to the command line).
Thanks,
-- Felipe
+
+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
--
2.20.1
_______________________________________________
Minios-devel mailing list
Minios-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/minios-devel
_______________________________________________
Minios-devel mailing list
Minios-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/minios-devel
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |