linux-kernel - Re: [RFC PATCH] /dev/mem: Add initial documentation of memory_open() and mem

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] [day] [month] [year] [list]

Message-ID: <CA+wEVJaGGQUisvKxk=1xxJWbao5iK50jByt244weAUvy0Hkc4g@mail.gmail.com>
Date: Sun, 24 Aug 2025 17:09:57 +0200
From: Gabriele Paoloni <gpaoloni@...hat.com>
To: Greg KH <gregkh@...uxfoundation.org>
Cc: arnd@...db.de, linux-kernel@...r.kernel.org, 
	safety-architecture@...ts.elisa.tech, Steven Rostedt <rostedt@...dmis.org>
Subject: Re: [RFC PATCH] /dev/mem: Add initial documentation of memory_open()
 and mem_fops

On Sat, Aug 23, 2025 at 10:01 AM Greg KH <gregkh@...uxfoundation.org> wrote:
>
> On Sat, Aug 23, 2025 at 09:48:32AM +0200, Gabriele Paoloni wrote:
> > > > > > + * - The file position '*ppos' shall be advanced by the number of bytes
> > > > > > + *   successfully copied from user space (including skipped bytes).
> > > > >
> > > > > No short summary first of what the function is supposed to do normally?
> > > > > Or are you relying on the few words at the top to summarize that?
> > > >
> > > > Function's expectations would define the testable behaviours (so they
> > > > are broken down into detailed expectations); nothing prevents to provide
> > > > an informative intro above "Function's expectations"; I could clarify this
> > > > in the patch for the doc-guide  and revisit this patch with informative intros
> > > > for all the functions....
> > >
> > > "testable behavior" is going to be very hard given that you are
> > > describing an internal-to-the-kernel function.  Good luck!
> >
> > Well that is something to be figured out (step by step :-) )
>
> Well what is your end-goal here?  Do you need/want all functions in the
> kernel to be documented like this, or do you only want those that are
> describing user-visable functionality?

Yes indeed. Possibly we could discuss with the KernelCI folks how
to define test cases and trace these to the code specifications.
In terms of priorities I would start from the functions that are
directly exposed
externally. I.e. those that specify the behaviour of syscalls, interrupt and
exception handlers, exported Kernel symbols.

>
> What is the requirement that is causing you to do this work?

The end goal would be to enhance the dependability of Linux so to make it
easier to adopt it in mission critical industries.
Depending on the industry and on the target integrity level, there can be
different demands on the documentation depth, however in general there
are two key principles that determine the dependability of SW:
a) The SW must be specified so that the integrator knows the expected
behaviour and the assumptions of use to be met to use the SW correctly
b) The SW must be verified (through tests and other measures) so that
it can be trusted to behave as specified in point a).

Now regardless of the target integrity level, the starting point would be
to specify the behaviour that is directly visible to the user and to kernel
drivers (as mentioned above).

Many Thanks
Gab

>
> thanks,
>
> greg k-h
>