adding a syscall to libc?

[Rick Macklem]

Konstantin Belousov wrote:
>On Sat, Jun 08, 2019 at 02:57:27AM +0000, Rick Macklem wrote:
>> Hi,
>>
First off, thanks Kostik for the fine explanation. I agree with Oliver that it should
be captured somewhere like the wiki. I'm no wiki guy, so hopefully someone else
will do this?

>> 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.
I could only find a Symbol.map in src/lib/libc/sys. I added it there and it seems to
work. (I am using a stable/12 source tree for testing the build/userland. I'll check
head in case it has moved.)

>'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:
Yes, I don't think I need the above.

>- Add the syscall to sys/kern/syscalls.master, and if reasonable,
>  to sys/compat/freebsd32/syscalls.master.
I don't think a 32bit binary on a 64bit system needs this for now.
(At least that's my understanding of what this is used for?)

>- 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).
It uses open fds, but I think I'll leave it out of capabilities.conf for now. If
there is a need, someone more familiar with capsicum can check it.

>- Add syscall prototype to the user-visible portion of header,
>  hiding it under the proper visibility check.
Hmm, not quite sure what you mean here. It ends up in sys/sysproto.h
automagically. Does it need to go somewhere else too?

>- Add syscall symbol to lib/libc/sys/Symbol.ver.
All I found was lib/libc/sys/Symbol.map and I've added it there.

>- 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.
I think it might be useful for the Linuxolator, since it is meant to be Linux
compatible, so I've done this.

>        - Consider the need to add auditing for new syscall.
This one I need to look at more closely. I may end up posting to the list
w.r.t. what to do about this. I think I'll leave it out of the first draft for phabricator.

>- Add man page for the syscall, at lib/libc/sys/YOURSYSCALL.2, and connect
>  it to the build in lib/libc/sys/Makefile.inc.
Yea, I know I have to write a man page. Maybe get to that tomorrow.

>- 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.
Righto, I'll do this when it gets to that stage.

Thanks again for the useful answer, rick