Re: [PATCH v2 2/2] docs-rst: userspace: update verbs API details

[Joel Nider]

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

> From: Matthew Wilcox <willy@xxxxxxxxxxxxx>
> To: Joel Nider <joeln@xxxxxxxxxx>
> Cc: Jonathan Corbet <corbet@xxxxxxx>, Jason Gunthorpe <jgg@xxxxxxxx>, 
Leon 
> Romanovsky <leon@xxxxxxxxxx>, Doug Ledford <dledford@xxxxxxxxxx>, Mike 
> Rapoport <rppt@xxxxxxxxxxxxx>, linux-doc@xxxxxxxxxxxxxxx, 
linux-kernel@xxxxxxxxxxxxxxx
> 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