Re: [PATCH v2 2/2] docs-rst: userspace: update verbs API details
Jonathan Corbet 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
Re: [PATCH v2 2/2] docs-rst: userspace: update verbs API details
Hi Jon, On Tue, Jan 15, 2019 at 02:38:59PM -0700, Jonathan Corbet wrote: > On Tue, 15 Jan 2019 22:37:01 +0200 > > 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. I believe its worth adding Documentation/doc-guide/where-to-put-stuff.rst with at least basic guidelines for the desired organization of Documentation/. > Thanks, > > jon > -- Sincerely yours, Mike.
Re: [PATCH v2 2/2] docs-rst: userspace: update verbs API details
On Tue, 15 Jan 2019 22:37:01 +0200 "Joel Nider" wrote: > Jonathan Corbet 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
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 , linux- > d...@vger.kernel.org, linux-kernel@vger.kernel.org, Mike Rapoport > Date: 01/15/2019 08:09 PM > Subject: Re: [PATCH v2 2/2] docs-rst: userspace: update verbs API details > > On Tue, 15 Jan 2019 18:29:59 +0200 > "Joel Nider" wrote: > > > > 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. > > 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 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_. > > 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 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. > > 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? > The project of reworking the kernel documentation to be more comprehensive > and more focused on its readers, rather than, as Rob Landley once put it, > "a gigantic mess, currently organized based on where random passers-by put > things down last" is still in an early stage. But that doesn't mean that > 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, it's > 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 >
Re: [PATCH v2 2/2] docs-rst: userspace: update verbs API details
On Tue, 15 Jan 2019 18:29:59 +0200 "Joel Nider" wrote: > > 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. 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 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_. 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 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. 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. The project of reworking the kernel documentation to be more comprehensive and more focused on its readers, rather than, as Rob Landley once put it, "a gigantic mess, currently organized based on where random passers-by put things down last" is still in an early stage. But that doesn't mean that we shouldn't try to always move in the right direction. 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, it's a starting place. Can I ask you to do that, please? Thanks, jon
Re: [PATCH v2 2/2] docs-rst: userspace: update verbs API details
Matthew Wilcox wrote on 01/15/2019 05:31:28 PM: > From: Matthew Wilcox > To: Joel Nider > Cc: Jonathan Corbet , Jason Gunthorpe , Leon > Romanovsky , Doug Ledford , Mike > Rapoport , linux-...@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
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.
