linux-kernel - Re: [PATCH 3/3] Documentation: Add real-time

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: <87v7ntdwp5.fsf@trenco.lwn.net>
Date: Tue, 15 Jul 2025 14:29:42 -0600
From: Jonathan Corbet <corbet@....net>
To: Sebastian Andrzej Siewior <bigeasy@...utronix.de>,
 linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
 linux-rt-devel@...ts.linux.dev
Cc: Boqun Feng <boqun.feng@...il.com>, Clark Williams
 <clrkwllms@...nel.org>, Frederic Weisbecker <frederic@...nel.org>, Ingo
 Molnar <mingo@...hat.com>, John Ogness <john.ogness@...utronix.de>, Peter
 Zijlstra <peterz@...radead.org>, Steven Rostedt <rostedt@...dmis.org>,
 Thomas Gleixner <tglx@...utronix.de>, Valentin Schneider
 <vschneid@...hat.com>, Waiman Long <longman@...hat.com>, Will Deacon
 <will@...nel.org>, Sebastian Andrzej Siewior <bigeasy@...utronix.de>
Subject: Re: [PATCH 3/3] Documentation: Add real-time

Sebastian Andrzej Siewior <bigeasy@...utronix.de> writes:

> Signed-off-by: Sebastian Andrzej Siewior <bigeasy@...utronix.de>
> ---
>  Documentation/index.rst                 |   1 +
>  Documentation/real-time/differences.rst | 244 ++++++++++++++++++++++++
>  Documentation/real-time/index.rst       |  18 ++
>  Documentation/real-time/theory.rst      | 119 ++++++++++++
>  4 files changed, 382 insertions(+)
>  create mode 100644 Documentation/real-time/differences.rst
>  create mode 100644 Documentation/real-time/index.rst
>  create mode 100644 Documentation/real-time/theory.rst

So overall it looks good, but I do have one overriding question:

- Who is the audience for this documentation?

I think it's an important question to ask, because something this easily
becomes an unorganized pile of stuff that somebody thought should be
written down somewhere - better than nothing, but hard for readers to
use effectively.

A good first step would be to supply a paragraph or two in the new
Documentation/real-time/index.rst describing the nature of the
documentation and who it is intended for.

Then ... think about whether a new top-level directory under
Documentation makes sense.  I've been working for years to reduce those,
so I tend to push back a little when new ones show up.

- Is this documentation for kernel developers in general, with the idea
  of maybe helping them to not break PREEMPT_RT so often?  Then perhaps
  documentation with that focus under core-api/ makes sense.

- Is it, instead, intended as overall design documentation?  We don't
  really have a good place for that now, maybe we need a new design/
  book to gather such material.

See what I'm getting at?  I'm not saying that these docs *have* to go
somewhere else, but I do think it's worth thinking about.

Thanks,

jon