| Message ID | xnikzeajcw.fsf@greed.delorie.com |
|---|---|
| State | New |
| Headers | show |
| Series | manual: add syscall list appendix | expand |
* DJ Delorie: > [the choice, wording, and formatting is - I admit - rough, but this > was the best I could come up with without feedback ;] > > diff --git a/manual/Makefile b/manual/Makefile > index b5fda4a7ae..1e2800f409 100644 > --- a/manual/Makefile > +++ b/manual/Makefile > @@ -55,7 +55,8 @@ examples = $(filter %.c.texi, $(texis)) > > # Generated files directly included from libc.texinfo. > libc-texi-generated = chapters.texi top-menu.texi dir-add.texi \ > - libm-err.texi version.texi pkgvers.texi > + libm-err.texi version.texi pkgvers.texi \ > + syscalls.texi > > # Add path to build dir for generated files > texis-path := $(filter-out $(libc-texi-generated) summary.texi $(examples), \ > @@ -138,6 +139,18 @@ $(objpfx)%.c.texi: examples/%.c > $< | expand > $@.new > mv -f $@.new $@ > > +# Generate a list of wrapped syscalls > +$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ; > +$(objpfx)stamp-syscalls: $(common-objpfx)config.make > + cat `find ../sysdeps -name syscalls.list -print` \ > + | sed -e '/^[^_a-zA-Z]/d' \ > + -e 's/[ \t].*//' \ > + -e 's/^/@code{/; s/$$/}/' \ > + | sort -u \ > + > $(objpfx)syscalls-tmp > + $(move-if-change) $(objpfx)syscalls-tmp $(objpfx)syscalls.texi > + touch $@ I ran the list through “sysdeps/unix/sysv/linux/glibcsyscalls.py query-syscall”, and the following system calls do not actually exist on any architecture: adjtime chflags fchflags getdomain getdtsz gethostid killpg klogctl lseek64 posix_fadvise64 revoke sched_getp sched_gets sched_primax sched_primin sched_setp sched_sets setdomain setegid seteuid sethostid setlogin sigpause sigstack syscall_clock_gettime Maybe we should clean this up and remove those from the syscalls.list files? In the other direction, the list contains setgid setuid, setregid, setreuid, which are not syscall wrappers by most definitions of the term because they involve the setXid broadcast. > +@Theglibc{} provides, in addition to its own API, an interface to the > +kernel for which it's configured. This interface is a purely > +mechanical translation from the kernel's ABI to the C ABI. Where such > +functions are not otherwise documented in this manual, please refer to > +the relvent kernel's documentation (for the Linux kernel, this is the > +@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project}) > +for information on calling these functions. Are the manual pages really official kernel documentation? They are out-of-tree, with separate maintainers, and a different development process. Thanks, Florian
On 5/16/24 1:02 AM, Florian Weimer wrote: > * DJ Delorie: > >> [the choice, wording, and formatting is - I admit - rough, but this >> was the best I could come up with without feedback ;] Adding Alejandro to TO: for any input. This needs a configure argument to specify which version of the Linux man-pages project release is the version we've looked at to make sure we match the behaviour for the specified syscalls. I think we should specifically reference e.g. Linux man-pages X.Y. >> diff --git a/manual/Makefile b/manual/Makefile >> index b5fda4a7ae..1e2800f409 100644 >> --- a/manual/Makefile >> +++ b/manual/Makefile >> @@ -55,7 +55,8 @@ examples = $(filter %.c.texi, $(texis)) >> >> # Generated files directly included from libc.texinfo. >> libc-texi-generated = chapters.texi top-menu.texi dir-add.texi \ >> - libm-err.texi version.texi pkgvers.texi >> + libm-err.texi version.texi pkgvers.texi \ >> + syscalls.texi >> >> # Add path to build dir for generated files >> texis-path := $(filter-out $(libc-texi-generated) summary.texi $(examples), \ >> @@ -138,6 +139,18 @@ $(objpfx)%.c.texi: examples/%.c >> $< | expand > $@.new >> mv -f $@.new $@ >> >> +# Generate a list of wrapped syscalls >> +$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ; >> +$(objpfx)stamp-syscalls: $(common-objpfx)config.make >> + cat `find ../sysdeps -name syscalls.list -print` \ >> + | sed -e '/^[^_a-zA-Z]/d' \ >> + -e 's/[ \t].*//' \ >> + -e 's/^/@code{/; s/$$/}/' \ >> + | sort -u \ >> + > $(objpfx)syscalls-tmp >> + $(move-if-change) $(objpfx)syscalls-tmp $(objpfx)syscalls.texi >> + touch $@ What about syscalls that have cancellation? We should really split them out and document that we wrap them in special cancellation code (which will change a bit as I need to review Adhemerval's changes for that). > I ran the list through “sysdeps/unix/sysv/linux/glibcsyscalls.py > query-syscall”, and the following system calls do not actually exist > on any architecture: > > adjtime chflags fchflags getdomain getdtsz gethostid killpg klogctl > lseek64 posix_fadvise64 revoke sched_getp sched_gets sched_primax > sched_primin sched_setp sched_sets setdomain setegid seteuid sethostid > setlogin sigpause sigstack syscall_clock_gettime > > Maybe we should clean this up and remove those from the syscalls.list > files? > > In the other direction, the list contains setgid setuid, setregid, > setreuid, which are not syscall wrappers by most definitions of the term > because they involve the setXid broadcast. > >> +@Theglibc{} provides, in addition to its own API, an interface to the >> +kernel for which it's configured. This interface is a purely >> +mechanical translation from the kernel's ABI to the C ABI. Where such >> +functions are not otherwise documented in this manual, please refer to >> +the relvent kernel's documentation (for the Linux kernel, this is the >> +@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project}) >> +for information on calling these functions. > > Are the manual pages really official kernel documentation? They are > out-of-tree, with separate maintainers, and a different development > process. I think we should be honest in this description. Suggest: ~~~ @Theglibc{} provides, in addition to its own API, an interface to the kernel for which it's configured. This interface is mostly a purely mechanical translation from the kernel's ABI to the C ABI. For the set of syscalls where we do not guarantee POSIX Thread cancellation the wrappers only organize the incoming arguments from the C calling convention to the calling convention of the target kernel. For the set of syscalls where we provided POSIX Thread cancellation the wrappers set some internal state in the library to support cancellation, but this does not impact the behaviour of the syscall provided by the kernel. @Theglibc{} includes by reference the Linux man-pages X.Y documentation to document the listed syscalls for the Linux kernel. For reference purposes only the latest @uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project} documentation can be accessed from the @uref{https://www.kernel.org,Linux kernel} website. Where the syscall has more specific documentation in this manual that more specific documentation is considered authoritative. ~~~ The intent is to say that if we didn't document anything in the glibc manual that users should feel free to go read the Linux man-pages documentaiton for that syscall. Thoughts?
* Carlos O'Donell: >>> +# Generate a list of wrapped syscalls >>> +$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ; >>> +$(objpfx)stamp-syscalls: $(common-objpfx)config.make >>> + cat `find ../sysdeps -name syscalls.list -print` \ >>> + | sed -e '/^[^_a-zA-Z]/d' \ >>> + -e 's/[ \t].*//' \ >>> + -e 's/^/@code{/; s/$$/}/' \ >>> + | sort -u \ >>> + > $(objpfx)syscalls-tmp >>> + $(move-if-change) $(objpfx)syscalls-tmp $(objpfx)syscalls.texi >>> + touch $@ > > What about syscalls that have cancellation? They have argument lists that start with C (usually Ci:). Thanks, Florian
Hey Carlos! On Thu, May 16, 2024 at 07:44:42AM GMT, Carlos O'Donell wrote: > On 5/16/24 1:02 AM, Florian Weimer wrote: > > * DJ Delorie: > > > >> [the choice, wording, and formatting is - I admit - rough, but this > >> was the best I could come up with without feedback ;] > > Adding Alejandro to TO: for any input. I'm not using the @gmail.com account anymore. I still have it forwarding to my current mailbox, to reveive mail sent to that address, but please don't send anything there, since some day I'll remove the account. Please use <alx@kernel.org> which now forwards to my new mailbox at <foss@alejandro-colomar.es>. > This needs a configure argument to specify which version of the Linux man-pages project > release is the version we've looked at to make sure we match the behaviour for the > specified syscalls. > > I think we should specifically reference e.g. Linux man-pages X.Y. I'll check later. Can you tell me a little bit more about what you're doing and what you want feedback about? Have a lovely day! Alex > > >> diff --git a/manual/Makefile b/manual/Makefile > >> index b5fda4a7ae..1e2800f409 100644 > >> --- a/manual/Makefile > >> +++ b/manual/Makefile > >> @@ -55,7 +55,8 @@ examples = $(filter %.c.texi, $(texis)) > >> > >> # Generated files directly included from libc.texinfo. > >> libc-texi-generated = chapters.texi top-menu.texi dir-add.texi \ > >> - libm-err.texi version.texi pkgvers.texi > >> + libm-err.texi version.texi pkgvers.texi \ > >> + syscalls.texi > >> > >> # Add path to build dir for generated files > >> texis-path := $(filter-out $(libc-texi-generated) summary.texi $(examples), \ > >> @@ -138,6 +139,18 @@ $(objpfx)%.c.texi: examples/%.c > >> $< | expand > $@.new > >> mv -f $@.new $@ > >> > >> +# Generate a list of wrapped syscalls > >> +$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ; > >> +$(objpfx)stamp-syscalls: $(common-objpfx)config.make > >> + cat `find ../sysdeps -name syscalls.list -print` \ > >> + | sed -e '/^[^_a-zA-Z]/d' \ > >> + -e 's/[ \t].*//' \ > >> + -e 's/^/@code{/; s/$$/}/' \ > >> + | sort -u \ > >> + > $(objpfx)syscalls-tmp > >> + $(move-if-change) $(objpfx)syscalls-tmp $(objpfx)syscalls.texi > >> + touch $@ > > What about syscalls that have cancellation? > > We should really split them out and document that we wrap them in special cancellation > code (which will change a bit as I need to review Adhemerval's changes for that). > > > I ran the list through “sysdeps/unix/sysv/linux/glibcsyscalls.py > > query-syscall”, and the following system calls do not actually exist > > on any architecture: > > > > adjtime chflags fchflags getdomain getdtsz gethostid killpg klogctl > > lseek64 posix_fadvise64 revoke sched_getp sched_gets sched_primax > > sched_primin sched_setp sched_sets setdomain setegid seteuid sethostid > > setlogin sigpause sigstack syscall_clock_gettime > > > > Maybe we should clean this up and remove those from the syscalls.list > > files? > > > > In the other direction, the list contains setgid setuid, setregid, > > setreuid, which are not syscall wrappers by most definitions of the term > > because they involve the setXid broadcast. > > > >> +@Theglibc{} provides, in addition to its own API, an interface to the > >> +kernel for which it's configured. This interface is a purely > >> +mechanical translation from the kernel's ABI to the C ABI. Where such > >> +functions are not otherwise documented in this manual, please refer to > >> +the relvent kernel's documentation (for the Linux kernel, this is the > >> +@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project}) > >> +for information on calling these functions. > > > > Are the manual pages really official kernel documentation? They are > > out-of-tree, with separate maintainers, and a different development > > process. > > I think we should be honest in this description. > > Suggest: > ~~~ > @Theglibc{} provides, in addition to its own API, an interface to the > kernel for which it's configured. This interface is mostly a purely > mechanical translation from the kernel's ABI to the C ABI. For the set > of syscalls where we do not guarantee POSIX Thread cancellation the > wrappers only organize the incoming arguments from the C calling convention > to the calling convention of the target kernel. For the set of syscalls > where we provided POSIX Thread cancellation the wrappers set some internal > state in the library to support cancellation, but this does not impact > the behaviour of the syscall provided by the kernel. > > @Theglibc{} includes by reference the Linux man-pages X.Y documentation > to document the listed syscalls for the Linux kernel. For reference purposes only > the latest @uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project} > documentation can be accessed from the @uref{https://www.kernel.org,Linux kernel} > website. Where the syscall has more specific documentation in this manual that > more specific documentation is considered authoritative. > ~~~ > > The intent is to say that if we didn't document anything in the glibc manual > that users should feel free to go read the Linux man-pages documentaiton for > that syscall. > > Thoughts? > > -- > Cheers, > Carlos. >
On 5/16/24 9:37 AM, Alejandro Colomar wrote: > Hey Carlos! > > On Thu, May 16, 2024 at 07:44:42AM GMT, Carlos O'Donell wrote: >> On 5/16/24 1:02 AM, Florian Weimer wrote: >>> * DJ Delorie: >>> >>>> [the choice, wording, and formatting is - I admit - rough, but this >>>> was the best I could come up with without feedback ;] >> >> Adding Alejandro to TO: for any input. > > I'm not using the @gmail.com account anymore. I still have it > forwarding to my current mailbox, to reveive mail sent to that address, > but please don't send anything there, since some day I'll remove the > account. Please use <alx@kernel.org> which now forwards to my new > mailbox at <foss@alejandro-colomar.es>. Done. Updated address book. >> This needs a configure argument to specify which version of the Linux man-pages project >> release is the version we've looked at to make sure we match the behaviour for the >> specified syscalls. >> >> I think we should specifically reference e.g. Linux man-pages X.Y. > > I'll check later. Can you tell me a little bit more about what you're > doing and what you want feedback about? Where glibc provides only syscall wrappers I want to include by reference the Linux man-pages descriptions, at a specific version, for the behaviour of those APIs. This has two positive benefits: - Focuses all of our efforts on keeping linux man-pages accurate for the syscall wrappers. - Provides glibc documentation for the APIs by way of a normative reference. - This may be required from a process perspective if anyone is using glibc in an implementation that attempts to attain standards conformance for the APIs in question e.g. ISO 9001, IEC 61508, IEC 61511-1, or ISO 26262. Right now we lack documentation for epoll for example in glibc, and to recreate that would be a lot of work, and I think a collaboration between the glibc manual and the Linux man-pages project would be a better solution.
Hi Carlos, On Thu, May 16, 2024 at 10:52:22AM GMT, Carlos O'Donell wrote: > >> This needs a configure argument to specify which version of the Linux man-pages project > >> release is the version we've looked at to make sure we match the behaviour for the > >> specified syscalls. > >> > >> I think we should specifically reference e.g. Linux man-pages X.Y. > > > > I'll check later. Can you tell me a little bit more about what you're > > doing and what you want feedback about? > > Where glibc provides only syscall wrappers I want to include by reference the Linux > man-pages descriptions, at a specific version, for the behaviour of those APIs. LGTM. For such change: Acked-by: Alejandro Colomar <alx@kernel.org> > This has two positive benefits: > > - Focuses all of our efforts on keeping linux man-pages accurate for the syscall > wrappers. > > - Provides glibc documentation for the APIs by way of a normative reference. > > - This may be required from a process perspective if anyone is using glibc > in an implementation that attempts to attain standards conformance for > the APIs in question e.g. ISO 9001, IEC 61508, IEC 61511-1, or ISO 26262. > > Right now we lack documentation for epoll for example in glibc, and to recreate > that would be a lot of work, and I think a collaboration between the glibc manual > and the Linux man-pages project would be a better solution. Sure! Whatever you need from me, please let me know. I'm also trying to write in the HISTORY section of manual pages any important changes that have affected functions, so if you want to add details to any page in those sections to make more clear the glibc versions that added support, or some other changes, they're very welcome. Have a lovely day! Alex
On Thu, May 16, 2024 at 1:38 PM DJ Delorie <dj@redhat.com> wrote: > > Florian Weimer <fweimer@redhat.com> writes: > > Maybe we should clean this up and remove those from the syscalls.list > > files? > > If this patch triggers a cleanup of syscall information, I'm all for > that ;-) > > I debated documenting the *found* syscalls vs the *listed* syscalls but > I didn't want the manual to be specific to the configured target. Hurd > doesn't have wrapped syscalls (I think ;) and BSD *is* listed with > syscalls, so those were included, along with all the Linux variants. > > >> +@Theglibc{} provides, in addition to its own API, an interface to the > >> +kernel for which it's configured. This interface is a purely > >> +mechanical translation from the kernel's ABI to the C ABI. Where such > >> +functions are not otherwise documented in this manual, please refer to > >> +the relvent kernel's documentation (for the Linux kernel, this is the relevant > >> +@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project}) > >> +for information on calling these functions. > > > > Are the manual pages really official kernel documentation? They are > > out-of-tree, with separate maintainers, and a different development > > process. > > They're way more official than the in-tree kernel documentation... oh > wait, the kernel has NO DOCUMENTATION ON ITS API. > > The man pages are more likely to be correct and up to date than the > glibc manual. The alternative is to duplicate all that work into the > glibc manual. > > Besides, I didn't say "official" I said "relevent" ;-) >
On Thu, May 16, 2024 at 01:55:08PM GMT, DJ Delorie wrote: > > The intent is to say that if we didn't document anything in the glibc manual > > that users should feel free to go read the Linux man-pages documentaiton for > > that syscall. > > > > Thoughts? > > It's long for an appendix. Do we have a chapter on cancellation? Do we > want to be that Linux-centric? Hi DJ, In the Linux man-pages project, we document primarily the Linux and glibc interfaces, but we also document the behavior of other systems such as the BSDs or musl when it differs, normally in the VERSIONS section. I would welcome patches for documenting for example GNU Hurd details, or any other (FOSS) systems that provide the same interfaces. And already during Michael Kerrisk's maintainership, he had a strong interest for documenting portability to other Unix systems. Have a lovely night! Alex
diff --git a/manual/Makefile b/manual/Makefile index b5fda4a7ae..1e2800f409 100644 --- a/manual/Makefile +++ b/manual/Makefile @@ -55,7 +55,8 @@ examples = $(filter %.c.texi, $(texis)) # Generated files directly included from libc.texinfo. libc-texi-generated = chapters.texi top-menu.texi dir-add.texi \ - libm-err.texi version.texi pkgvers.texi + libm-err.texi version.texi pkgvers.texi \ + syscalls.texi # Add path to build dir for generated files texis-path := $(filter-out $(libc-texi-generated) summary.texi $(examples), \ @@ -138,6 +139,18 @@ $(objpfx)%.c.texi: examples/%.c $< | expand > $@.new mv -f $@.new $@ +# Generate a list of wrapped syscalls +$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ; +$(objpfx)stamp-syscalls: $(common-objpfx)config.make + cat `find ../sysdeps -name syscalls.list -print` \ + | sed -e '/^[^_a-zA-Z]/d' \ + -e 's/[ \t].*//' \ + -e 's/^/@code{/; s/$$/}/' \ + | sort -u \ + > $(objpfx)syscalls-tmp + $(move-if-change) $(objpfx)syscalls-tmp $(objpfx)syscalls.texi + touch $@ + $(objpfx)%.info: %.texinfo LANGUAGE=C LC_ALL=C $(MAKEINFO) -P $(objpfx) --output=$@ $< diff --git a/manual/platform.texi b/manual/platform.texi index 478b6fdcdf..92541208a5 100644 --- a/manual/platform.texi +++ b/manual/platform.texi @@ -2,12 +2,13 @@ @c %MENU% Describe all platform-specific facilities provided @appendix Platform-specific facilities -@Theglibc{} can provide machine-specific functionality. +@Theglibc{} can provide machine-specific and kernel-specific functionality. @menu * PowerPC:: Facilities Specific to the PowerPC Architecture * RISC-V:: Facilities Specific to the RISC-V Architecture * X86:: Facilities Specific to the X86 Architecture +* Syscalls:: System Call Interface for Supported Kernels @end menu @node PowerPC @@ -772,3 +773,21 @@ avx_active (void) return CPU_FEATURE_ACTIVE (AVX); @} @end smallexample + +@node Syscalls +@appendixsec Kernel System Calls + +@Theglibc{} provides, in addition to its own API, an interface to the +kernel for which it's configured. This interface is a purely +mechanical translation from the kernel's ABI to the C ABI. Where such +functions are not otherwise documented in this manual, please refer to +the relvent kernel's documentation (for the Linux kernel, this is the +@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project}) +for information on calling these functions. + +The comprehensive list of kernel system calls that may be mapped to C +functions follows. Note that this list includes calls for all kernels +@theglibc{} supports, whereas in the real world only those calls +supported by the configured and/or running kernel will be available. + +@include{syscalls.texi}