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 wrote: > > > On Sat, Jun 08, 2019 at 02:57:27AM +, 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 signature.asc Description: PGP signature
Re: adding a syscall to libc?
On Sun, Jun 09, 2019 at 06:12:59AM +, Rick Macklem wrote: > Konstantin Belousov wrote: > >On Sat, Jun 08, 2019 at 02:57:27AM +, 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? There is apparently https://wiki.freebsd.org/AddingSyscalls which is already quite comprehensive. I am adding missed information right now. > > >> 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.) Yes, Symbol.map, it was thinko. > > >'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?) Right. > > >- 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? sys/sysproto.h is not used by userspace. If your syscall is going to be useful for normal userspace (it should be, othewise why adding it at all ?) you have to declare it in some header typically used by apps. Take for example include/unistd.h, where you should only add the syscall to appropriate namespace, allowing strict standard-compliance compiler option to hide symbols not specified by choosen standard. I suspect that you need #if __BSD_VISIBLE int your_syscall(args); #endif if the header is defined e.g. by POSIX. > > >- 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
Re: adding a syscall to libc?
Konstantin Belousov wrote: >On Sat, Jun 08, 2019 at 02:57:27AM +, 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 ___ freebsd-current@freebsd.org mailing list https://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: adding a syscall to libc?
On Saturday, June 8, 2019, Konstantin Belousov wrote: > On Sat, Jun 08, 2019 at 02:57:27AM +, 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@freebsd.org mailing list > > https://lists.freebsd.org/mailman/listinfo/freebsd-current > > To unsubscribe, send any mail to " > freebsd-current-unsubscr...@freebsd.org" > ___ > freebsd-current@freebsd.org mailing list > https://lists.freebsd.org/mailman/listinfo/freebsd-current > To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org" > ___ freebsd-current@freebsd.org mailing list https://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: adding a syscall to libc?
On Sat, Jun 08, 2019 at 02:57:27AM +, 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. > > 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@freebsd.org mailing list > https://lists.freebsd.org/mailman/listinfo/freebsd-current > To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org" ___ freebsd-current@freebsd.org mailing list https://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
adding a syscall to libc?
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?) 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@freebsd.org mailing list https://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
