Re: [Minios-devel] [UNIKRAFT PATCH 5/6] doc: Raw system calls with syscall_shim

[Gaulthier Gain <Gaulthier.Gain@xxxxxxxxx>]

Reviewed-by: Gaulthier Gain <gaulthier.gain@xxxxxxxxx>

> On 11 Dec 2019, at 15:19, Simon Kuenzer <simon.kuenzer@xxxxxxxxx> wrote:
> 
> Update the documentation to reflect the differentiation of raw and
> libc-style system call implementations.
> 
> Signed-off-by: Simon Kuenzer <simon.kuenzer@xxxxxxxxx>
> ---
> doc/guides/developers-app.rst | 135 ++++++++++++++++++++++++++--------
> 1 file changed, 106 insertions(+), 29 deletions(-)
> 
> diff --git a/doc/guides/developers-app.rst b/doc/guides/developers-app.rst
> index d288bb61..5b5f0918 100644
> --- a/doc/guides/developers-app.rst
> +++ b/doc/guides/developers-app.rst
> @@ -324,50 +324,127 @@ This will add the section .uk_fs_list after the .text
> Syscall shim layer
> ============================
> 
> -If you library provides a syscall, you need to inform Unikraft that it
> -can use your implementation. Add a line in you Makefile.uk: ::
> +The system call shim layer (``lib/syscall_shim``) provides Linux-style 
> mappings
> +of system call numbers to actual system call handler functions. You can
> +implement a system call handler by using one of the definition macros
> +(``UK_SYSCALL_DEFINE``, ``UK_SYSCALL_R_DEFINE``) and register the system
> +call by adding it to ``UK_PROVIDED_SYSCALLS-y`` within your ``Makefile.uk``.
> 
> -    UK_PROVIDED_SYSCALLS-$(CONFIG_LIBYOURLIBNAME) += 
> <syscall_name>-<number_of_arguments>
> +The shim layer library supports two implementation variants for system call
> +handlers:
> 
> -Where `<number_of_arguments>` is how many arguments your syscall accepts.
> +(1) libc-style: The function implementation returns ``-1`` and sets ``errno``
> +    in case of errors
> 
> -For example: ::
> +(2) and raw: The function implementation returns a negative error value in 
> case
> +    of errors. ``errno`` is not used at all.
> +
> +Because of library internals, each system call implementation needs to be
> +provided with both variants. The build option `Drop unused functions and 
> data`
> +is making sure that only the variants are compiled-in that are actually in 
> use.
> 
> -    UK_PROVIDED_SYSCALLS-$(CONFIG_LIBVFSCORE) += writev-3
> +You can use helper macros in order to implement the call just once. The first
> +variant can be implemented with the ``UK_SYSCALL_DEFINE`` macro:
> 
> -.. note:: Please consult corresponding man page in order to keep API
> -           matching to the equivalent linux syscall
> +.. code-block:: c
> +
> +    UK_SYSCALL_DEFINE(return_type, syscall_name, arg1_type, arg1_name,
> +                                                 arg2_type, arg2_name, ..)
> +    {
> +        /* ... */
> +    }
> 
> -For the implementation of you syscall use the following template:
> +Example:
> 
> .. code-block:: c
> 
> -  UK_SYSCALL_DEFINE(syscall_name, arg1_type, arg1_name, arg2_type, 
> arg2_name, ..)
> -  {
> -     ret = do_cool_stuff();
> -     if (ret) {
> -             errno = ERROR_CODE;
> -             return -1;
> -     }
> -     return 0;
> -  }
> +    #include <uk/syscall.h>
> +
> +    UK_SYSCALL_DEFINE(ssize_t, write, int, fd, const void *, buf, size_t, 
> count)
> +    {
> +        ssize_t ret;
> 
> -For example:
> +        ret = vfs_do_write(fd, buf, count);
> +        if (ret < 0) {
> +            errno = EFAULT;
> +            return -1;
> +        }
> +        return ret;
> +    }
> +
> +
> +Raw implementations should use the ``UK_SYSCALL_R_DEFINE`` macro:
> 
> .. code-block:: c
> 
> -  UK_SYSCALL_DEFINE(writev, unsigned long, fd, const struct iovec *, vec,
> -               unsigned long, vlen)
> -  {
> -     return pwritev(fd, vec, vlen, -1);
> -  }
> +    UK_SYSCALL_R_DEFINE(return_type, syscall_name, arg1_type, arg1_name,
> +                                                   arg2_type, arg2_name, ..)
> +    {
> +        /* ... */
> +    }
> +
> +Example:
> +
> +.. code-block:: c
> +
> +    #include <uk/syscall.h>
> +
> +    UK_SYSCALL_R_DEFINE(ssize_t, write, int, fd, const void *, buf, size_t, 
> count)
> +    {
> +        long ret;
> +
> +        ret = (long) vfs_do_write(fd, buf, count);
> +        if (ret < 0) {
> +            return -EFAULT;
> +        }
> +        return ret;
> +    }
> +
> +Please note that in the raw case (``UK_SYSCALL_R_DEFINE``), the return type
> +within your code block is always ``long``. The specified return type as
> +parameter to the macro will be used for the libc-style wrapper. However, the
> +input parameters are defined with the actual type for your code block.
> +
> +Both macros create the following three symbols:
> +
> +.. code-block:: c
> +
> +    /* libc-style system call that returns -1 and sets errno on errors */
> +    long uk_syscall_e_<syscall_name>(long <arg1_name>, long <arg2_name>, 
> ...);
> +
> +    /* Raw system call that returns negative error codes on errors */
> +    long uk_syscall_r_<syscall_name>(long <arg1_name>, long <arg2_name>, 
> ...);
> +
> +    /* libc-style wrapper (the same as uk_syscall_e_<syscall_name> but with 
> actual types) */
> +    <return_type> <syscall_name>(<arg1_type> <arg1_name>,
> +                                 <arg2_type> <arg2_name>, ...);
> +
> +Note: When `syscall_shim` library is not enabled, the original design idea 
> was
> +that the macros provide the libc-style wrapper only. However, both macros
> +provide always all three variants. This is done to support the case that a
> +system call is implemented on top of another.
> +
> +If your library uses an ``exportsyms.uk`` file, you need to add the three
> +symbols for making them public available: ::
> +
> +   uk_syscall_e_<syscallname>
> +   uk_syscall_r_<syscallname>
> +   <syscallname>
> +
> +In our example: ::
> +
> +   uk_syscall_e_write
> +   uk_syscall_r_write
> +   write
> +
> +In order to register the system call to `syscall_shim`, add it to
> +``UK_PROVIDED_SYSCALLS-y`` with the library ``Makefile.uk``: ::
> +
> +   UK_PROVIDED_SYSCALLS-$(CONFIG_<YOURLIB>) += 
> <syscall_name>-<number_of_arguments>
> 
> -Please note, that syscall_shim expects behavior as described in ``man 2
> -syscall``. Namely: ::
> +The ``Makefile.uk`` snippet for our example: ::
> 
> -  The return value is defined by the system call being invoked.  In
> -  general, a 0 return value indicates success.  A -1 return value
> -  indicates an error, and an error code is stored in errno.
> +   UK_PROVIDED_SYSCALLS-$(CONFIG_LIBWRITESYS) += write-3
> 
> ==================================
> Command line arguments in Unikraft
> -- 
> 2.20.1
> 


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