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  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]
Date:   Tue, 15 Jan 2019 22:37:01 +0200
From:   "Joel Nider" <>
To:     Jonathan Corbet <>
Cc:     Doug Ledford <>, Jason Gunthorpe <>,
        Leon Romanovsky <>,,, Mike Rapoport <>,
        Matthew Wilcox <>
Subject: Re: [PATCH v2 2/2] docs-rst: userspace: update verbs API details

Jonathan Corbet <> wrote on 01/15/2019 08:08:54 PM:

> From: Jonathan Corbet <>
> To: "Joel Nider" <>
> Cc: Matthew Wilcox <>, Doug Ledford 
> Jason Gunthorpe <>, Leon Romanovsky <>, 
>,, Mike Rapoport 
> Date: 01/15/2019 08:09 PM
> Subject: Re: [PATCH v2 2/2] docs-rst: userspace: update verbs API 
> On Tue, 15 Jan 2019 18:29:59 +0200
> "Joel Nider" <> wrote:
> > > I think this is a horrible direction to take.  The current document 
> > > clearly for _users_.  All this documentation you've added is for 
> > > hackers.  It needs to go in a different file, or not be added at 
> > > 
> > 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 
> > interface. 
> One has to start somewhere - I'm glad to see you adding to it.
> > 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 
> > more kernel docs is a good thing). So let's assume for the moment that 
> > _should_ be added, and that we are discussing _where_.
> I think we definitely want to add it.
> > 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 
> > from the same problem. There is a section (7) called "Low Level 
> > which documents very much the same level of detail as the Infiniband 
> > 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 
> > pages, #2 is web search for an example (I know for many it's the other 
> > 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, 
> > not from the application writer's perspective - it should be about how 
> > create a consistent API for users, from the kernel hacker's 
> The intent behind the user-space API manual is to document the 
> API; it's meant to be read by people writing applications and such.
> Perhaps they find it with a web search, but it will be there for them, 
> hopes, when they want it.

So is the intent then to duplicate what is already in 'man'? Why would we 
want 2 different locations for basically the same information? Wouldn't it 
make more sense to just put these few details into appropriate 'man' 

> The project of reworking the kernel documentation to be more 
> and more focused on its readers, rather than, as Rob Landley once put 
> "a gigantic mess, currently organized based on where random passers-by 
> things down last" is still in an early stage.  But that doesn't mean 
> we shouldn't try to always move in the right direction. 

It looks like I misunderstood the purpose of the "userspace API" section 
then. So is there a section that is meant for a guide on how to write an 
interface function?

> So I agree with
> Willy that this particular text is better suited to the driver-API
> manual.  Even if a bare bit of information on its own there for now, 
> a starting place.  Can I ask you to do that, please?

OK, just to be clear - you are asking me to leave the original file as-is 
(well, after .rst conversion) but move it to the new location 
(Documentation/userspace-api), and put my new content into a new file in 
the old location (Documentation/infiniband)?
> Thanks,
> jon

Powered by blists - more mailing lists