linux-kernel - Re: Explicitly defining the userspace API

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <YmA/jFztk5GkjIr2@kroah.com>
Date:   Wed, 20 Apr 2022 19:14:52 +0200
From:   Greg KH <gregkh@...uxfoundation.org>
To:     Spencer Baugh <sbaugh@...ern.com>
Cc:     linux-api@...r.kernel.org, linux-kernel@...r.kernel.org,
        marcin@...zkiewicz.com.pl, torvalds@...ux-foundation.org,
        arnd@...db.de
Subject: Re: Explicitly defining the userspace API

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