Re: adding a syscall to libc?

On Saturday, June 8, 2019, Konstantin Belousov <kostikbel_at_gmail.com> wrote:

> On Sat, Jun 08, 2019 at 02:57:27AM +0000, Rick Macklem wrote:
> > Hi,
> >
> > I've started working of a copy_file_range() syscall for FreeBSD. I think
> I have the
> > kernel patched and ready for some testing.
> > However, I'm confused about what I need to do in src/lib/libc/sys?
> > - Some syscalls have little .c files, but other ones do not.
> >   When is one of these little .c files needed and, when not needed, what
> else
> >   needs to be done? (I notice that syscall.mk in src/sys/sys
> automagically, but
> >   I can't see what else, if anything, needs to be done?)
> Most important is to add the new syscall public symbol to sys/Symbol.map
> into the correct version, FBSD_1.6 for CURRENT-13.  Do no bother with
> __sys_XXX and __XXX aliases.
>
> 'Tiny .c files' are typically used for one of two purposes:
> - Convert raw kernel interface into something expected by userspace,
>   often this coversion uses more generic and non-standard interface to
>   implement more usual function.  Examples are open(2) or waitid(2)
>   which are really tiny wrappers around openat(2) and wait6(2) in
>   today libc.
> - Allow libthr to hook into libc to provide additional services.  Libthr
>   often has to modify semantic of raw syscall, and libc contains the
>   tables redirecting to implementation, the tables are patched on libthr
>   load.  Since tables must fill entries with some address in case libthr
>   is not loaded, tiny functions which wrap syscalls are created for
>   use in that tables.
>
> I think you do not need anything that complications for start, in which
> case adding new syscall consists of the following steps:
> - Add the syscall to sys/kern/syscalls.master, and if reasonable,
>   to sys/compat/freebsd32/syscalls.master.
> - Consider if the syscall makes sense in capsicumized environment,
>   and if yes, list the syscall in sys/kern/capabilities.conf.  Typically,
>   if syscall provides access to the global files namespace, it must be not
>   allowed.  On the other hand, if syscall only operates on already opened
>   file descriptors, then it is suitable (but of course there are lot of
>   nuances).
> - Add syscall prototype to the user-visible portion of header,
>   hiding it under the proper visibility check.
> - Add syscall symbol to lib/libc/sys/Symbol.ver.
> - Implement the syscall.  There are some additional details that might
>   require attention:
>         - If compat32 syscall going to be implemented, or you know
>           that Linuxolator needs to implement same syscall and would
>           like to take advantage of the code, provide
>                 int kern_YOURSYSCALL();
>           wrapper and declare it in sys/syscallsubr.h.  Real
> implementations
>           of host-native and compat32 sys_YOURSYSCALL() should be just
>           decoding of uap members and call into kern_YOURSYSCALL.
>         - Consider the need to add auditing for new syscall.
> - Add man page for the syscall, at lib/libc/sys/YOURSYSCALL.2, and connect
>   it to the build in lib/libc/sys/Makefile.inc.
> - When creating review for the change, do not include diff for generated
>   files after make sysent.  Similarly, when doing the commit, first commit
>   everything non-generated, then do make -C sys/kern sysent (and
>   make sysent -C sys/compat/freebsd32 sysent if appropriate) and commit
>   the generated files in follow-up.


The best place for this little writeup would be in the wiki. ;)



>
> >
> > Thanks in advance for your help, rick
> > ps: I am using the Linux man pages for the syscall ABI. At some point,
> I'll put this
> >       in phabricator and post here for comments/review.
> > _______________________________________________
> > freebsd-current_at_freebsd.org mailing list
> > https://lists.freebsd.org/mailman/listinfo/freebsd-current
> > To unsubscribe, send any mail to "
> freebsd-current-unsubscribe_at_freebsd.org"
> _______________________________________________
> freebsd-current_at_freebsd.org mailing list
> https://lists.freebsd.org/mailman/listinfo/freebsd-current
> To unsubscribe, send any mail to "freebsd-current-unsubscribe_at_freebsd.org"
>