linux-kernel - Re: [RFC PATCH v5 2/3] docs: scheduler: Add scheduler overview documentation

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: <20200529081021.013e37d9@lwn.net>
Date:   Fri, 29 May 2020 08:10:21 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Peter Zijlstra <peterz@...radead.org>
Cc:     john mathew <john.mathew@...kie.com>, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org, mingo@...hat.com,
        juri.lelli@...hat.com, vincent.guittot@...aro.org,
        dietmar.eggemann@....com, rostedt@...dmis.org, bsegall@...gle.com,
        mgorman@...e.de, bristot@...hat.com, tsbogend@...ha.franken.de,
        lukas.bulwahn@...il.com, x86@...nel.org,
        linux-mips@...r.kernel.org, tglx@...utronix.de,
        mostafa.chamanara@...il.com, willy@...radead.org,
        valentin.schneider@....com, rdunlap@...radead.org,
        Mostafa Chamanara <mostafa.chamanara@...emark.com>,
        Oleg Tsymbal <oleg.tsymbal@...kie.com>
Subject: Re: [RFC PATCH v5 2/3] docs: scheduler: Add scheduler overview
 documentation

On Fri, 29 May 2020 13:00:12 +0200
Peter Zijlstra <peterz@...radead.org> wrote:

> > +**Thermal Pressure**:  
> 
> I find these attached headers really hard to read. And what's with the
> ** stuff ?
> 
> Other files in this same patch use a different style:
> 
> Header
> ------
> test goes here,
> 
> Which I find a lot more readable. Use it here too?

Normal headers would seem to be appropriate here, yes.

> > +process runs when. In that context, it has the following tasks:
> > +
> > +* share CPU cores equally among all currently running processes.
> > +* pick appropriate process to run next if required, considering scheduling
> > +  class/policy and process priorities.
> > +* balance processes between multiple cores in SMP systems.  
> 
> indent the bullets at least one space, like:
> 
>  * share CPU cores...
>  * pick ..
> 
> Write it like you want to read this as a text document. Ignore all that
> RST bullshit.

The "RST bullshit" can handle a leading space there just fine.

> > +Runqueue
> > +~~~~~~~~
> > +
> > +:c:type:`struct rq <rq>` is the central data structure of process  
> 
> I so hate that rst crap; John, can't we teach the thing that anything
> called 'struct foo' or 'foo_t' is in fact a C type, just like we did
> with foo() being a function?

Yes, we can, we're just waiting for somebody (perhaps even me) to find the
time to do it. Until then, I think we can probably just leave :c:type: out
entirely.

jon