Message-Id: <OF64BB6EB2.8999493B-ONC2258383.0058B5B7-C2258383.005AA2FD@notes.na.collabserv.com>
Date:   Tue, 15 Jan 2019 18:29:59 +0200
From:   "Joel Nider" <JOELN@...ibm.com>
To:     Matthew Wilcox <willy@...radead.org>
Cc:     Jonathan Corbet <corbet@....net>,
        Doug Ledford <dledford@...hat.com>,
        Jason Gunthorpe <jgg@...pe.ca>,
        Leon Romanovsky <leon@...nel.org>, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org, Mike Rapoport <rppt@...ux.ibm.com>
Subject: Re: [PATCH v2 2/2] docs-rst: userspace: update verbs API details

Matthew Wilcox <willy@...radead.org> wrote on 01/15/2019 05:31:28 PM:

> From: Matthew Wilcox <willy@...radead.org>
> To: Joel Nider <joeln@...ibm.com>
> Cc: Jonathan Corbet <corbet@....net>, Jason Gunthorpe <jgg@...pe.ca>, 
Leon 
> Romanovsky <leon@...nel.org>, Doug Ledford <dledford@...hat.com>, Mike 
> Rapoport <rppt@...ux.ibm.com>, linux-doc@...r.kernel.org, 
linux-kernel@...r.kernel.org
> Date: 01/15/2019 05:31 PM
> Subject: Re: [PATCH v2 2/2] docs-rst: userspace: update verbs API 
details
> 
> On Tue, Jan 15, 2019 at 12:26:31PM +0200, Joel Nider wrote:
> > It is important to understand the existing framework when implementing
> > a new verb. The majority of existing API functions are implemented 
using
> > the write syscall, but this has been superceded by the ioctl syscall
> > for new commands. This patch updates the documentation regarding how
> > to go about implementing a new verb, focusing on the new ioctl
> > interface.
> > 
> > The documentation is far from complete, but this is a good step in the
> > right direction. Future patches can add more detail according to need.
> > Also, the interface is still undergoing substantial changes so an
> > effort was made to document only the stable parts so as to avoid
> > incorrect information since documentation changes tend to lag behind
> > code changes.
> 
> I think this is a horrible direction to take.  The current document is
> clearly for _users_.  All this documentation you've added is for kernel
> hackers.  It needs to go in a different file, or not be added at all.
> 
Hmm, that's a bit heavy-handed in my opinion. If you look at what is 
currently under "Userspace API", there are a total of 4 files - not 
exactly what I would call comprehensive documentation of the Linux kernel 
interface. So the option of not adding more documentation simply because 
it is in the wrong section seems a bit defeatist (I think we can all agree 
more kernel docs is a good thing). So let's assume for the moment that it 
_should_ be added, and that we are discussing _where_. Yes, the document I 
am modifying has a bit of a mash of pure userspace API - functions and 
details that application developers must know - and the lower level 
details that are more useful for someone who wishes to extend this 
interface. The existing documentation (specifically unshare) also suffers 
from the same problem. There is a section (7) called "Low Level Design" 
which documents very much the same level of detail as the Infiniband doc, 
so this seems to be at least consistent.
I think there is a deeper issue - as an application developer, I would 
only look at this kernel documentation as a last resort. #1 is the 'man' 
pages, #2 is web search for an example (I know for many it's the other way 
around). So who really looks at this documentation? I say the vast 
majority is kernel hackers. So yes, this is about the user-facing API, but 
not from the application writer's perspective - it should be about how to 
create a consistent API for users, from the kernel hacker's perspective.

Joel

Powered by blists - more mailing lists