From: Greg KH <gregkh@linuxfoundation.org>
To: Spencer Baugh <sbaugh@catern.com>
Cc: linux-api@vger.kernel.org, linux-kernel@vger.kernel.org,
marcin@juszkiewicz.com.pl, torvalds@linux-foundation.org,
arnd@arndb.de
Subject: Re: Explicitly defining the userspace API
Date: Wed, 20 Apr 2022 19:14:52 +0200 [thread overview]
Message-ID: <YmA/jFztk5GkjIr2@kroah.com> (raw)
In-Reply-To: <874k2nhgtg.fsf@catern.com>
On Wed, Apr 20, 2022 at 04:15:25PM +0000, Spencer Baugh wrote:
>
> Linux guarantees the stability of its userspace API, but the API
> itself is only informally described, primarily with English prose. I
> want to add an explicit, authoritative machine-readable definition of
> the Linux userspace API.
>
> As background, in a conventional libc like glibc, read(2) calls the
> Linux system call read, passing arguments in an architecture-specific
> way according to the specific details of read.
>
> The details of these syscalls are at best documented in manpages, and
> often defined only by the implementation. Anyone else who wants to
> work with a syscall, in any way, needs to duplicate all those details.
>
> So the most basic definition of the API would just represent the
> information already present in SYSCALL_DEFINE macros: the C types of
> arguments and return values. More usefully, it would describe the
> formats of those arguments and return values: that the first argument
> to read is a file descriptor rather than an arbitrary integer, and
> what flags are valid in the flags argument of openat, and that open
> returns a file descriptor. A step beyond that would be describing, in
> some limited way, the effects of syscalls; for example, that read
> writes into the passed buffer the number of bytes that it returned.
So how would you define read() in this format in a way that has not
already been attempted in the past? How are you going to define a
format that explains functionality in a way that is not just the
implementation in the end?
> One step in this direction is Documentation/ABI, which specifies the
> stability guarantees for different userspace APIs in a semi-formal
> way. But it doesn't specify the actual content of those APIs, and it
> doesn't cover individual syscalls at all.
The content is described in Documentation/ABI/ entries, where do you see
that missing?
And you are correct, that place does not describe syscalls, or other
user/kernel interfaces that predate sysfs.
good luck!
greg k-h
next prev parent reply other threads:[~2022-04-20 17:15 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-04-20 16:15 Explicitly defining the userspace API Spencer Baugh
2022-04-20 17:14 ` Greg KH [this message]
2022-05-06 16:59 ` Spencer Baugh
2022-04-20 17:18 ` Jann Horn
2022-04-21 11:33 ` Arnd Bergmann
2022-04-20 17:52 ` Marcin Juszkiewicz
2022-04-21 9:57 ` Cyril Hrubis
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=YmA/jFztk5GkjIr2@kroah.com \
--to=gregkh@linuxfoundation.org \
--cc=arnd@arndb.de \
--cc=linux-api@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=marcin@juszkiewicz.com.pl \
--cc=sbaugh@catern.com \
--cc=torvalds@linux-foundation.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).