Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   Jonathan Corbet <corbet@lwn.net>
To:     Peter Oskolkov <posk@google.com>
Cc:     Peter Zijlstra <peterz@infradead.org>,
        Ingo Molnar <mingo@redhat.com>,
        Thomas Gleixner <tglx@linutronix.de>,
        Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
        linux-api <linux-api@vger.kernel.org>,
        Paul Turner <pjt@google.com>, Ben Segall <bsegall@google.com>,
        Peter Oskolkov <posk@posk.io>,
        Joel Fernandes <joel@joelfernandes.org>,
        Andrew Morton <akpm@linux-foundation.org>,
        Andrei Vagin <avagin@google.com>,
        Jim Newsome <jnewsome@torproject.org>
Subject: Re: [RFC PATCH v0.1 0/9] UMCG early preview/RFC patchset
In-Reply-To: <CAPNVh5feas6o_8pk5-kiujTDJf6XT4uxapxC4eZokaj+iv=rqQ@mail.gmail.com>
References: <20210520183614.1227046-1-posk@google.com>
 <87mtspm7fe.fsf@meer.lwn.net>
 <CAPNVh5eV+CtY74_JMv6_Bm5aCVBh_F9hkWLT6v3BT=H0UwodUg@mail.gmail.com>
 <87eee0m8ez.fsf@meer.lwn.net>
 <CAPNVh5fhkgscs44Lpj3DPBrA9NrhFohUpRwpT2iMM1BDBcLW4A@mail.gmail.com>
 <87wnrrlwv0.fsf@meer.lwn.net>
 <CAPNVh5feas6o_8pk5-kiujTDJf6XT4uxapxC4eZokaj+iv=rqQ@mail.gmail.com>
Date:   Thu, 27 May 2021 09:41:32 -0600
Message-ID: <87h7io421f.fsf@meer.lwn.net>
MIME-Version: 1.0
Content-Type: text/plain
Precedence: bulk

Peter Oskolkov <posk@google.com> writes:

> I've pasted below the content of umcg.rst file that I'll add as a doc
> patch to the next version of the patchset. I've also attached a PDF
> version of the file rendered, in case it is useful. I also think that
> it is a bit early for manpages - I expect the API and/or behavior to
> change quite a bit before this is all merged. I'm also not completely
> sure whether the manpages should describe the "porcelain API" or the
> "plumbing API" (see the .rst below).
>
> Please let me know if you have any questions, comments, or suggestions.

So this is very helpful, thanks.  I've been through it once, and have
some overall comments.

 - Parts of it read more like a requirements document.  A document going
   into the kernel should describe what the code actually does, not what
   we think it should be.

 - I would make a serious effort to get a handle on the terminology.
   The term "kernel thread" has a meaning other than the one you give
   it; saying "kernel thread" here will lead to a lot of confusion.  I
   hesitate to suggest terms because I'm terrible at naming (just ask my
   kids), but I would pick clear and concise names for your "server
   threads" and "worker threads", then stick to them.

 - The library documentation is good to have, but it will really be
   necessary to document the system calls as well.  *That* is the part
   that the kernel community will have to support forever if this is
   merged.

Thanks,

jon