lkml.org 
[lkml]   [2019]   [Jan]   [15]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
SubjectRe: [PATCH v2 2/2] docs-rst: userspace: update verbs API details
From
Date
Matthew Wilcox <willy@infradead.org> wrote on 01/15/2019 05:31:28 PM:

> From: Matthew Wilcox <willy@infradead.org>
> To: Joel Nider <joeln@il.ibm.com>
> Cc: Jonathan Corbet <corbet@lwn.net>, Jason Gunthorpe <jgg@ziepe.ca>,
Leon
> Romanovsky <leon@kernel.org>, Doug Ledford <dledford@redhat.com>, Mike
> Rapoport <rppt@linux.ibm.com>, linux-doc@vger.kernel.org,
linux-kernel@vger.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

\
 
 \ /
  Last update: 2019-01-15 17:30    [W:0.071 / U:72.584 seconds]
©2003-2018 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site