Re: adding a syscall to libc?

On Sat, Jun 08, 2019 at 01:47:39PM +0200, Oliver Pinter wrote:
> 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. ;)

I wrote the initial version of this page long ago:
https://wiki.freebsd.org/AddingSyscalls

-- Brooks