[1] was an initial proposal defining testable code specifications for
some functions in /drivers/char/mem.c.
However a Guideline to write such specifications was missing and test
cases tracing to such specifications were missing.
This patchset represents a next step and is organised as follows:
- patch 1/3 contains the Guideline for writing code specifications
- patch 2/3 contains examples of code specfications defined for some
  functions of drivers/char/mem.c
- patch 3/3 contains examples of selftests that map to some code
  specifications of patch 2/3

[1] https://lore.kernel.org/all/20250821170419.70668-1-gpaoloni@redhat.com/
---
Changes from v1:
1) Added a Guideline to write code specifications in the Linux Kernel
Documentation
2) Addressed Greg KH comments in /drivers/char/mem.c
3) Added example of test cases mapping to the code specifications in
/drivers/char/mem.c
---
Alessandro Carminati (1):
  selftests/devmem: initial testset

Gabriele Paoloni (2):
  Documentation: add guidelines for writing testable code specifications
  /dev/mem: Add initial documentation of memory_open() and mem_fops

 .../doc-guide/code-specifications.rst         | 208 +++++++
 Documentation/doc-guide/index.rst             |   1 +
 drivers/char/mem.c                            | 231 ++++++-
 tools/testing/selftests/Makefile              |   1 +
 tools/testing/selftests/devmem/Makefile       |  13 +
 tools/testing/selftests/devmem/debug.c        |  25 +
 tools/testing/selftests/devmem/debug.h        |  14 +
 tools/testing/selftests/devmem/devmem.c       | 200 ++++++
 tools/testing/selftests/devmem/ram_map.c      | 250 ++++++++
 tools/testing/selftests/devmem/ram_map.h      |  38 ++
 tools/testing/selftests/devmem/secret.c       |  46 ++
 tools/testing/selftests/devmem/secret.h       |  13 +
 tools/testing/selftests/devmem/tests.c        | 569 ++++++++++++++++++
 tools/testing/selftests/devmem/tests.h        |  45 ++
 tools/testing/selftests/devmem/utils.c        | 379 ++++++++++++
 tools/testing/selftests/devmem/utils.h        | 119 ++++
 16 files changed, 2146 insertions(+), 6 deletions(-)
 create mode 100644 Documentation/doc-guide/code-specifications.rst
 create mode 100644 tools/testing/selftests/devmem/Makefile
 create mode 100644 tools/testing/selftests/devmem/debug.c
 create mode 100644 tools/testing/selftests/devmem/debug.h
 create mode 100644 tools/testing/selftests/devmem/devmem.c
 create mode 100644 tools/testing/selftests/devmem/ram_map.c
 create mode 100644 tools/testing/selftests/devmem/ram_map.h
 create mode 100644 tools/testing/selftests/devmem/secret.c
 create mode 100644 tools/testing/selftests/devmem/secret.h
 create mode 100644 tools/testing/selftests/devmem/tests.c
 create mode 100644 tools/testing/selftests/devmem/tests.h
 create mode 100644 tools/testing/selftests/devmem/utils.c
 create mode 100644 tools/testing/selftests/devmem/utils.h

-- 
2.48.1

On Wed, Sep 10, 2025 at 06:59:57PM +0200, Gabriele Paoloni wrote:
> [1] was an initial proposal defining testable code specifications for
> some functions in /drivers/char/mem.c.
> However a Guideline to write such specifications was missing and test
> cases tracing to such specifications were missing.
> This patchset represents a next step and is organised as follows:
> - patch 1/3 contains the Guideline for writing code specifications
> - patch 2/3 contains examples of code specfications defined for some
>   functions of drivers/char/mem.c
> - patch 3/3 contains examples of selftests that map to some code
>   specifications of patch 2/3
> 
> [1] https://lore.kernel.org/all/20250821170419.70668-1-gpaoloni@redhat.com/

"RFC" implies there is a request.  I don't see that here, am I missing
that?  Or is this "good to go" and want us to seriously consider
accepting this?

thanks,

greg k-h

Hi Greg

On Tue, Oct 21, 2025 at 9:35 AM Greg KH <gregkh@linuxfoundation.org> wrote:
>
> On Wed, Sep 10, 2025 at 06:59:57PM +0200, Gabriele Paoloni wrote:
> > [1] was an initial proposal defining testable code specifications for
> > some functions in /drivers/char/mem.c.
> > However a Guideline to write such specifications was missing and test
> > cases tracing to such specifications were missing.
> > This patchset represents a next step and is organised as follows:
> > - patch 1/3 contains the Guideline for writing code specifications
> > - patch 2/3 contains examples of code specfications defined for some
> >   functions of drivers/char/mem.c
> > - patch 3/3 contains examples of selftests that map to some code
> >   specifications of patch 2/3
> >
> > [1] https://lore.kernel.org/all/20250821170419.70668-1-gpaoloni@redhat.com/
>
> "RFC" implies there is a request.  I don't see that here, am I missing
> that?  Or is this "good to go" and want us to seriously consider
> accepting this?

I assumed that an RFC (as in request for comments) that comes with proposed
changes to upstream files would be interpreted as a request for feedbacks
associated with the proposed changes (what is wrong or what is missing);
next time I will communicate the request explicitly.

WRT this specific patchset, the intent is to introduce formalism in specifying
code behavior (so that the same formalism can also be used to write and
review test cases), so my high level asks would be:

1) In the first part of patch 1/3 we explain why we are doing this and the high
level goals. Do you agree with these? Are these clear?

2) In the rest of the patchset we introduce the formalism, we propose some
specs (in patch 2) and associated selftests (in patch 3). Please let us know
if there is something wrong, missing or to be improved.

Thanks and kind regards
Gab

>
> thanks,
>
> greg k-h
>

On Tue, Oct 21, 2025 at 11:42:24AM +0200, Gabriele Paoloni wrote:
> Hi Greg
> 
> On Tue, Oct 21, 2025 at 9:35 AM Greg KH <gregkh@linuxfoundation.org> wrote:
> >
> > On Wed, Sep 10, 2025 at 06:59:57PM +0200, Gabriele Paoloni wrote:
> > > [1] was an initial proposal defining testable code specifications for
> > > some functions in /drivers/char/mem.c.
> > > However a Guideline to write such specifications was missing and test
> > > cases tracing to such specifications were missing.
> > > This patchset represents a next step and is organised as follows:
> > > - patch 1/3 contains the Guideline for writing code specifications
> > > - patch 2/3 contains examples of code specfications defined for some
> > >   functions of drivers/char/mem.c
> > > - patch 3/3 contains examples of selftests that map to some code
> > >   specifications of patch 2/3
> > >
> > > [1] https://lore.kernel.org/all/20250821170419.70668-1-gpaoloni@redhat.com/
> >
> > "RFC" implies there is a request.  I don't see that here, am I missing
> > that?  Or is this "good to go" and want us to seriously consider
> > accepting this?
> 
> I assumed that an RFC (as in request for comments) that comes with proposed
> changes to upstream files would be interpreted as a request for feedbacks
> associated with the proposed changes (what is wrong or what is missing);
> next time I will communicate the request explicitly.
> 
> WRT this specific patchset, the intent is to introduce formalism in specifying
> code behavior (so that the same formalism can also be used to write and
> review test cases), so my high level asks would be:
> 
> 1) In the first part of patch 1/3 we explain why we are doing this and the high
> level goals. Do you agree with these? Are these clear?

No, and no.

I think this type of thing is, sadly, folly.  You are entering into a
path that never ends with no clear goal that you are conveying here to
us.

I might be totally wrong, but I fail to see what you want to have happen
in the end.

Every in-kernel api documented in a "formal" way like this?  Or a
subset?  If a subset, which ones specifically?  How many?  And who is
going to do that?  And who is going to maintain it?  And most
importantly, why is it needed at all?

For some reason Linux has succeeded in pretty much every place an
operating system is needed for cpus that it can run on (zephyr for those
others that it can not.)  So why are we suddenly now, after many
decades, requiring basic user/kernel stuff to be formally documented
like this?

In the past, when we have had "validating bodies" ask for stuff like
this, the solution is to provide it in a big thick book, outside of the
kernel, by the company that wishes to sell such a product to that
organization to justify the cost of doing that labor.  In every instance
that I know of, that book sits on a shelf and gathers dust, while Linux
is just updated over the years in those sites to new versions and the
book goes quickly out of date as no one really cares about it, except
it having been a check-box for a purchase order requirement.

That's business craziness, no need to get us involved in all of that.
Heck, look at the stuff around FIPS certification for more insanity.
That's a check-box that is required by organizations and then totally
ignored and never actually run at all by the user.  I feel this is much
the same.

So step back, and tell us exactly what files and functions and apis are
needed to be documented in this stilted and formal way, who exactly is
going to be doing all of that work, and why we should even consider
reviewing and accepting and most importantly, maintaining such a thing
for the next 40+ years.

> 2) In the rest of the patchset we introduce the formalism, we propose some
> specs (in patch 2) and associated selftests (in patch 3). Please let us know
> if there is something wrong, missing or to be improved.

I made many comments on patch 3, the most important one being that the
tests created do not seem to follow any of the standards we have for
Linux kernel tests for no documented reason.

The irony of submitting tests for formal specifications that do not
follow documented policies is rich :)

thanks,

greg k-h

Hi Greg

On Tue, Oct 21, 2025 at 6:46 PM Greg KH <gregkh@linuxfoundation.org> wrote:
>
> On Tue, Oct 21, 2025 at 11:42:24AM +0200, Gabriele Paoloni wrote:
> > Hi Greg
> >
> > On Tue, Oct 21, 2025 at 9:35 AM Greg KH <gregkh@linuxfoundation.org> wrote:
> > >
> > > On Wed, Sep 10, 2025 at 06:59:57PM +0200, Gabriele Paoloni wrote:
> > > > [1] was an initial proposal defining testable code specifications for
> > > > some functions in /drivers/char/mem.c.
> > > > However a Guideline to write such specifications was missing and test
> > > > cases tracing to such specifications were missing.
> > > > This patchset represents a next step and is organised as follows:
> > > > - patch 1/3 contains the Guideline for writing code specifications
> > > > - patch 2/3 contains examples of code specfications defined for some
> > > >   functions of drivers/char/mem.c
> > > > - patch 3/3 contains examples of selftests that map to some code
> > > >   specifications of patch 2/3
> > > >
> > > > [1] https://lore.kernel.org/all/20250821170419.70668-1-gpaoloni@redhat.com/
> > >
> > > "RFC" implies there is a request.  I don't see that here, am I missing
> > > that?  Or is this "good to go" and want us to seriously consider
> > > accepting this?
> >
> > I assumed that an RFC (as in request for comments) that comes with proposed
> > changes to upstream files would be interpreted as a request for feedbacks
> > associated with the proposed changes (what is wrong or what is missing);
> > next time I will communicate the request explicitly.
> >
> > WRT this specific patchset, the intent is to introduce formalism in specifying
> > code behavior (so that the same formalism can also be used to write and
> > review test cases), so my high level asks would be:
> >
> > 1) In the first part of patch 1/3 we explain why we are doing this and the high
> > level goals. Do you agree with these? Are these clear?
>
> No, and no.
>
> I think this type of thing is, sadly, folly.  You are entering into a
> path that never ends with no clear goal that you are conveying here to
> us.
>
> I might be totally wrong, but I fail to see what you want to have happen
> in the end.
>
> Every in-kernel api documented in a "formal" way like this?  Or a
> subset?  If a subset, which ones specifically?  How many?  And who is
> going to do that?  And who is going to maintain it?  And most
> importantly, why is it needed at all?
>
> For some reason Linux has succeeded in pretty much every place an
> operating system is needed for cpus that it can run on (zephyr for those
> others that it can not.)  So why are we suddenly now, after many
> decades, requiring basic user/kernel stuff to be formally documented
> like this?

Let me try to answer starting from the "why".
IMO There are 2 aspects to consider.
The first one is that requirements/specification and associated tests
are valuable in claiming that Linux can be used in safety critical industries
(like automotive or aerospace).
The second one (that goes beyond the business need) is that the duality
of specifications and tests VS code increases the dependability of the
code itself so that its expected behaviour and associated constraints
are clear to the user and there is evidence of the code behaving as specified
(I already tried to address this point in [1]).
Some evidence of improvements can be found in the experiments we did.
E.g.:
- this [2] is a bug found in __ftrace_event_enable_disable()
- this [3] is a code optimization that came as we looked at the
specifications of
  __ftrace_event_enable_disable()
- here [4] we have documented assumptions of use that must be met when
  invoking event_enable_read(), otherwise there could be a wrong event status
  being reported to the user.

Finally the need for having specifications/requirements associated with Kernel
code has been already discussed at LPC'24 last year ([5]) and we got a thumb
up from some key maintainers with initial directions (hence we started
this activity).

[1] https://lore.kernel.org/all/CA+wEVJatTLKt-3HxyExtXf4M+fmD6pXcmmCuhd+3-n2J_2Tw8A@mail.gmail.com/
[2] https://lore.kernel.org/all/20250321170821.101403-1-gpaoloni@redhat.com/
[3] https://lore.kernel.org/all/20250723144928.341184323@kernel.org/
[4] https://lore.kernel.org/all/20250814122206.109096-1-gpaoloni@redhat.com/
[5] https://lpc.events/event/18/contributions/1894/

Now I'll try to answer about the goals.
I do not expect to have all Kernel APIs to be specified according
to the format that we are proposing; my initial goal is to have such
a formalism to be available in the Kernel so that developers that
need to write such specifications have a guideline available.
For example today we have a guideline to write kernel-doc comments,
however (AFAIK) patch acceptance is not gated by these being
present or not.
I think that developers having a direct interest can write such
specifications and associated tests and these could be reviewed and
eventually accepted by maintainers.

>
> In the past, when we have had "validating bodies" ask for stuff like
> this, the solution is to provide it in a big thick book, outside of the
> kernel, by the company that wishes to sell such a product to that
> organization to justify the cost of doing that labor.  In every instance
> that I know of, that book sits on a shelf and gathers dust, while Linux
> is just updated over the years in those sites to new versions and the
> book goes quickly out of date as no one really cares about it, except
> it having been a check-box for a purchase order requirement.

I agree and in fact a key ask from maintainers, as we discussed at
LPC'24 in [5], was to have the code specifications sitting next to the
code so that they could be maintainable as the code evolves (and they
would be even more maintainable if specs come with tests that can flag
regressions as the code evolves).

>
> That's business craziness, no need to get us involved in all of that.
> Heck, look at the stuff around FIPS certification for more insanity.
> That's a check-box that is required by organizations and then totally
> ignored and never actually run at all by the user.  I feel this is much
> the same.
>
> So step back, and tell us exactly what files and functions and apis are
> needed to be documented in this stilted and formal way, who exactly is
> going to be doing all of that work, and why we should even consider
> reviewing and accepting and most importantly, maintaining such a thing
> for the next 40+ years.

Putting business needs aside, I would expect maintainers, today, to
happily accept kernel-doc compliant code documentation as well as kunit
or selftests associated with the code; simply because they add technical
value.
If my assumption here is correct, having these kernel-doc specifications
clearly formalised should be an improvement for the maintainers (since
it would be easier to verify incoming patches when specs and tests are
in place and also it would be easier for a developer to write such
patches).

WRT the scope of code to be documented, I expect that to depend on
the vested interest of companies contributing to it.
The directions from the LPC24 session were to start with some pilot
drivers/subsystems first to define 'how' to specify the code and later
focus on what and scale...

>
> > 2) In the rest of the patchset we introduce the formalism, we propose some
> > specs (in patch 2) and associated selftests (in patch 3). Please let us know
> > if there is something wrong, missing or to be improved.
>
> I made many comments on patch 3, the most important one being that the
> tests created do not seem to follow any of the standards we have for
> Linux kernel tests for no documented reason.
>
> The irony of submitting tests for formal specifications that do not
> follow documented policies is rich :)

Thanks for your comments and sorry for the mistakes, I see that Alessandro
replied so we'll pay more attention in writing tests in the next revision.

Kind Regards
Gab

>
> thanks,
>
> greg k-h
>

On Wed, Oct 22, 2025 at 04:06:10PM +0200, Gabriele Paoloni wrote:
> > Every in-kernel api documented in a "formal" way like this?  Or a
> > subset?  If a subset, which ones specifically?  How many?  And who is
> > going to do that?  And who is going to maintain it?  And most
> > importantly, why is it needed at all?
> >
> > For some reason Linux has succeeded in pretty much every place an
> > operating system is needed for cpus that it can run on (zephyr for those
> > others that it can not.)  So why are we suddenly now, after many
> > decades, requiring basic user/kernel stuff to be formally documented
> > like this?
> 
> Let me try to answer starting from the "why".

Let's ignore the "why" for now, and get to the "how" and "what" which
you skipped from my questions above.

_Exactly_ how many in-kernel functions are you claiming is needed to be
documented in this type of way before Linux would become "acceptable" to
these regulatory agencies, and which ones _specifically_ are they?

Without knowing that, we could argue about the format all day long, and
yet have nothing to show for it.

And then, I have to ask, exactly "who" is going to do that work.

I'll point at another "you must do this for reasons" type of request we
have had in the past, SPDX.  Sadly that task was never actually finished
as it looks like no one really cared to do the real work involved.  We
got other benefits out of that effort, but the "goal" that people
started that effort with was never met.  Part of that is me not pushing
back hard enough on the "who is going to do the work" part of that
question, which is important in stuff like this.

If you never complete the effort, your end goal of passing Linux off to
those customers will never happen.

So, try to answer that, with lots and lots of specifics, and then, if we
agree that it is a sane thing to attempt (i.e. you are going to do all
the work and it actually would be possible to complete), then we can
argue about the format of the text :)

thanks,

greg k-h

On Wed, Oct 22, 2025 at 5:13 PM Greg KH <gregkh@linuxfoundation.org> wrote:
>
> On Wed, Oct 22, 2025 at 04:06:10PM +0200, Gabriele Paoloni wrote:
> > > Every in-kernel api documented in a "formal" way like this?  Or a subset?
> > > If a subset, which ones specifically?  How many?  And who is going to do
> > > that?  And who is going to maintain it?  And most importantly, why is it
> > > needed at all?

I appreciate the questions. I sense there may be some confusion over who this
is intended to benefit.

The design of the Linux kernel is emergent. This is a fundamental property of
the way it is developed, and the source of its greatest strength. But it has
some shortcomings that place a burden on kernel maintainers, all kernel
testing, and even people who wish to contribute.

We intend this as a tool to address those areas.


> > > For some reason Linux has succeeded in pretty much every place an
> > > operating system is needed for cpus that it can run on (zephyr for those
> > > others that it can not.)  So why are we suddenly now, after many decades,
> > > requiring basic user/kernel stuff to be formally documented like this?

You are correct, the kernel has succeeded over many decades, and will continue
succeeding for many decades to come.

With the exception of some very narrow situations, the emergent design (or
"nuanced complexity" if you prefer that term) of the Linux kernel is not
communicated in a broadly consistent way. This affects the way the kernel is
tested, and also the way it is developed. Even veteran kernel maintainers are
tripping over nuance and complexity.


> > Let me try to answer starting from the "why".
>
> Let's ignore the "why" for now, and get to the "how" and "what" which you
> skipped from my questions above.
>
> _Exactly_ how many in-kernel functions are you claiming is needed to be
> documented in this type of way before Linux would become "acceptable" to
> these regulatory agencies, and which ones _specifically_ are they?

Exactly zero. This is not for regulators.


> Without knowing that, we could argue about the format all day long, and
> yet have nothing to show for it.

As this is not intended for regulators, it is not clear to me that catering to
their desires would be a good use of anyone's time.

I say this as a software engineer who works in a _highly_ regulated industry,
and who knows the relevant regulations quite well. There are good ideas buried
in those regulations, but (in their default form) they are _not_ appropriate
for the Linux kernel development process.


> And then, I have to ask, exactly "who" is going to do that work.

The intent is to allow for a separate maintainer path. There is more to it than
that, but I do not want to bury the lede here.


> I'll point at another "you must do this for reasons" type of request we have
> had in the past, SPDX.  Sadly that task was never actually finished as it
> looks like no one really cared to do the real work involved.  We got other
> benefits out of that effort, but the "goal" that people started that effort
> with was never met.  Part of that is me not pushing back hard enough on the
> "who is going to do the work" part of that question, which is important in
> stuff like this.

Well, I am sorry for that. I am not quite sure how to respond, but I certainly
sympathize with past frustrations. I have plenty of my own.

We are not offering a silver bullet here, and the work to describe the kernel's
design will be finished when the work of development is finished. This is just
an attempt to fill in a semantic gap that is responsible for a great deal of
technical debt and maintainer burnout.


> If you never complete the effort, your end goal of passing Linux off to those
> customers will never happen.

It is not clear to me what customers you are talking about. That is certainly
not a goal in the mind of anyone working on this project that I am aware of.


> So, try to answer that, with lots and lots of specifics, and then, if we
> agree that it is a sane thing to attempt (i.e. you are going to do all the
> work and it actually would be possible to complete), then we can argue about
> the format of the text :)

I respect what you are saying here, and perhaps the point of confusion came
from the safety related source? As is often the case in science and
engineering, we are borrowing (and _heavily_ modifying) a technique that is
found in a different domain.

The intent is to target technical debt and maintainer burnout by filling in a
semantic gap that occurs when a human idea is turned into code. Ironically,
this is why the safety regulations were written in the first place, but little
consideration was given to development methodology during that process.

Thank you,

..Ch:W..

On Fri, Nov 07, 2025 at 04:29:13PM +0000, Chuck Wolber wrote:
> On Wed, Oct 22, 2025 at 5:13 PM Greg KH <gregkh@linuxfoundation.org> wrote:
> >
> > On Wed, Oct 22, 2025 at 04:06:10PM +0200, Gabriele Paoloni wrote:
> > > > Every in-kernel api documented in a "formal" way like this?  Or a subset?
> > > > If a subset, which ones specifically?  How many?  And who is going to do
> > > > that?  And who is going to maintain it?  And most importantly, why is it
> > > > needed at all?
> 
> I appreciate the questions. I sense there may be some confusion over who this
> is intended to benefit.
> 
> The design of the Linux kernel is emergent. This is a fundamental property of
> the way it is developed, and the source of its greatest strength. But it has
> some shortcomings that place a burden on kernel maintainers, all kernel
> testing, and even people who wish to contribute.

What specific burden?  A lack of documentation?  Something else?  How
are we surviving without this "standardized" interface so far?  Are you
a maintainer that runs into this issue in the past?

> We intend this as a tool to address those areas.

What tool exactly?  And who is asking for this?

> > > > For some reason Linux has succeeded in pretty much every place an
> > > > operating system is needed for cpus that it can run on (zephyr for those
> > > > others that it can not.)  So why are we suddenly now, after many decades,
> > > > requiring basic user/kernel stuff to be formally documented like this?
> 
> You are correct, the kernel has succeeded over many decades, and will continue
> succeeding for many decades to come.
> 
> With the exception of some very narrow situations, the emergent design (or
> "nuanced complexity" if you prefer that term) of the Linux kernel is not
> communicated in a broadly consistent way. This affects the way the kernel is
> tested, and also the way it is developed. Even veteran kernel maintainers are
> tripping over nuance and complexity.

We all trip over nuance and complexity, but I do not belive that adding
more formal comments is going to solve that (hint, the proof is on
you...)

> > > Let me try to answer starting from the "why".
> >
> > Let's ignore the "why" for now, and get to the "how" and "what" which you
> > skipped from my questions above.
> >
> > _Exactly_ how many in-kernel functions are you claiming is needed to be
> > documented in this type of way before Linux would become "acceptable" to
> > these regulatory agencies, and which ones _specifically_ are they?
> 
> Exactly zero. This is not for regulators.

Great!  Then we don't have to do anything and you all can stop it with
the "we need this to pass certification reviews" nonsense.  :)

> > Without knowing that, we could argue about the format all day long, and
> > yet have nothing to show for it.
> 
> As this is not intended for regulators, it is not clear to me that catering to
> their desires would be a good use of anyone's time.

Agreed!

> > And then, I have to ask, exactly "who" is going to do that work.
> 
> The intent is to allow for a separate maintainer path. There is more to it than
> that, but I do not want to bury the lede here.

But that's the real issue.  We've seen loads of proposals in the past
that have gone no where as no one actually does the real work.

Heck, look at SPDX, that "simple" work isn't yet done because no one
actually funded it, they just "demanded" that we implement SPDX tags for
all files, and when the work got hard, everyone ran away.

What makes you believe that documenting something that is orders of
magnitude more complex than something as "simple" as SPDX is going to
actually happen to our codebase?

> > So, try to answer that, with lots and lots of specifics, and then, if we
> > agree that it is a sane thing to attempt (i.e. you are going to do all the
> > work and it actually would be possible to complete), then we can argue about
> > the format of the text :)
> 
> I respect what you are saying here, and perhaps the point of confusion came
> from the safety related source? As is often the case in science and
> engineering, we are borrowing (and _heavily_ modifying) a technique that is
> found in a different domain.
> 
> The intent is to target technical debt and maintainer burnout by filling in a
> semantic gap that occurs when a human idea is turned into code. Ironically,
> this is why the safety regulations were written in the first place, but little
> consideration was given to development methodology during that process.

So I don't see the real goal here.  You all for some reason want to
"formalize" a documentation process of all kernel apis internally, for
the sole reason of making developer's and maintainer's lives easier?

Again, who is actually going to do that work?  And if you are, great,
just start sending out patches today using the format that we already
have for kerneldoc and the like.  No need for formal language
requirements here as obviously no tool is going to be parsing this, nor
as you said, any regulator is going to be reading this.

So let's just stick with the style that we have already, no need to
change anything, just start sending documentation patches!

thanks,

greg k-h