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] [day] [month] [year] [list]

Message-Id: <OF50C1BD06.78985B8A-ONC2258384.004ECD0A-C2258385.0024016B@notes.na.collabserv.com>
Date:   Thu, 17 Jan 2019 08:33:17 +0200
From:   "Joel Nider" <JOELN@...ibm.com>
To:     Jonathan Corbet <corbet@....net>
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

Jonathan Corbet <corbet@....net> wrote on 01/15/2019 11:38:59 PM:

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

My next task is to update the man pages for rdma-core since I touched 
libibverbs as well (the _other_ side of this API). So I just want to make 
sure everything is documented exactly once (no more, no less) and in the 
correct place.

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

I took a quick look at what is already there, and I don't see how the RDMA 
stuff fits. It looks like the majority is about various busses (SPI, PCI, 
I2C, USB, etc) or other general platform support (clk, edac) that I would 
use when writing a driver. My changes are very infiniband-specific, and 
user-facing and don't really seem to fit in with the aforementioned 
modules. It seems to me that if it does not belong in userspace-api, then 
leaving it where it is is the best choice.

Regards,
Joel