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

lists.openwall.net		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 linux-hardening linux-cve-announce 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]

Message-ID: <20190115143859.4cbd5d9c@lwn.net>
Date:   Tue, 15 Jan 2019 14:38:59 -0700
From:   Jonathan Corbet <corbet@....net>
To:     "Joel Nider" <JOELN@...ibm.com>
Cc:     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>,
        Matthew Wilcox <willy@...radead.org>
Subject: Re: [PATCH v2 2/2] docs-rst: userspace: update verbs API details

On Tue, 15 Jan 2019 22:37:01 +0200
"Joel Nider" <JOELN@...ibm.com> wrote:

> Jonathan Corbet <corbet@....net> wrote on 01/15/2019 08:08:54 PM:
> > The intent behind the user-space API manual is to document the user-space
> > 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, one
> > 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' 
> pages?

We are not attempting to duplicate the man pages; there's been occasional
talk of bringing them into the kernel tree, but enthusiasm for that is
scarce for a number of good reasons.  But there's a lot of information
about the user-space API that isn't in the man pages, including the piece
you are converting to RST.

For a huge example, look at the massive v4l2 UAPI documentation that's in
the kernel; that will never really fit into the man-page model.  (And yes,
it belongs in the userspace-api directory but isn't there for $REASONS).

> 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?

For something like this, driver-api seems like the right place.  Someday,
in some glorious future, it could contain a full manual on how these
drivers are written, using all of the nice kerneldoc comments that already
exist under drivers/infiniband.

> 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)?

I'd rather see you put the new stuff under Documentation/driver-api, either
in a standalone file or in a new subdirectory.

Thanks for your patience with this!  We really do want people to contribute
more documentation, and I feel bad when it seems like I'm making it
harder.  My hope is that it will pay off in the long run; I think there are
signs already that this is happening.

Thanks,

jon