[RFC 3/4] Documentation: move dma-buf documentation to rst
Hi Markus, On 11 August 2016 at 17:28, Markus Heiser wrote: > Hi Sumit, > > I haven't compiled your patch yet, just my 2cent about the > reStructuredText (reST) ASCII markup ... > Thanks very much for your detailed review comments - highly appreciated! > Here are some handy links about reST and the Sphinx markup constructs, > we have not yet added to the documentation (sorry): > > * reST primer:http://www.sphinx-doc.org/en/stable/rest.html > * reST quickref: http://docutils.sourceforge.net/docs/user/rst/quickref.html > * Sphinx markup constructs: > http://www.sphinx-doc.org/en/stable/markup/index.html > * Sphinx domains: http://www.sphinx-doc.org/en/stable/domains.html > * Sphinx cross references: > http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations > > Am 11.08.2016 um 12:47 schrieb Sumit Semwal : > >> Branch out dma-buf related documentation into its own rst file to allow >> adding it to the sphinx documentation generated. >> >> While at it, move dma-buf-sharing.txt into rst as the dma-buf guide too. >> >> Signed-off-by: Sumit Semwal > ... >> +dma-buf operations for device dma only >> +== >> + >> +The dma_buf buffer sharing API usage contains the following steps: >> + >> +1. Exporter announces that it wishes to export a buffer >> +2. Userspace gets the file descriptor associated with the exported buffer, >> and >> + passes it around to potential buffer-users based on use case >> +3. Each buffer-user 'connects' itself to the buffer >> +4. When needed, buffer-user requests access to the buffer from exporter >> +5. When finished with its use, the buffer-user notifies end-of-DMA to >> exporter >> +6. when buffer-user is done using this buffer completely, it 'disconnects' >> + itself from the buffer. >> + >> + >> +1. Exporter's announcement of buffer export >> +--- > > I can't recommend numbering the (sub-) sections explicit, even if you here > wanted to numerate the steps. Most often section numbers are controlled by > the subordinate toctree directive and this might not fit to the step > numbers. > > * > http://www.sphinx-doc.org/en/stable/markup/toctree.html?highlight=toc#the-toc-tree > >> + >> + The buffer exporter announces its wish to export a buffer. In this, it >> + connects its own private buffer data, provides implementation for >> operations >> + that can be performed on the exported :c:type:`dma_buf`, and flags for >> the file >> + associated with this buffer. All these fields are filled in struct >> + :c:type:`dma_buf_export_info`, defined via the >> DEFINE_DMA_BUF_EXPORT_INFO macro. >> + > > In restructuredText whitespace are markups. > > Do not indent if you don't want to create a (indented) block. I recommend to > drop > the two spaces in front of the paragraphs. > > IMHO you have to decide if you like to use sectioning (drop the to spaces) > or stay with the two spaces and use an enumeration list. If you wan't to stay > with the enumeration write: > > |1. Exporter's announcement of buffer export > | > | The buffer exporter announces its wish to export a buffer. In this, it > | connects its own private buffer .. > | ... > > Understood; will correct. >> + Interface: >> + :c:type:`DEFINE_DMA_BUF_EXPORT_INFO(exp_info) >> ` > > If haven't tested your patch, but I guess this will result in a Warning. > > the markup ":c:type" is a reference to a typedef description > > * http://www.sphinx-doc.org/en/stable/domains.html#role-c:type > > If the description is given, you can use the short form > > :c:type:`DEFINE_DMA_BUF_EXPORT_INFO` > > but I think, this is a function, not a typedef. > I did test it before sending out the RFC, and didn't get any warnings. This, btw, is a macro, so I guess that's why no warning. While on this topic, in my experimentation, if I just use the short form, the resultant text doesn't include the "(exp_info)" part as shown above. >> + >> + :c:func:`struct dma_buf *dma_buf_export(struct dma_buf_export_info >> *exp_info)` > > short form to refer > > :c:func:`dma_buf_export()` > When I last tried the short form, it only gave me a link to the full definition, and I wanted to have the arguments also shown here, so that the explanation below was easier. Though I think I tried without the (), so will try again and let you know. >> + >> + If this succeeds, dma_buf_export allocates a dma_buf structure, and >> + returns a pointer to the same. It also associates an anonymous file with >> this >> + buffer, so it can be exported. On failure to allocate the dma_buf object, >> + it returns NULL. >> + >> + 'exp_name' in struct dma_buf_export_info is the name of exporter - to >> + facilitate information while debugging. It is set to KBUILD_MODNAME by > > If you want to render a constant in a monospace font you can use the > inline markup ``KBUILD_MODNAME``, but if you want. > Thanks, will do. >> +
[RFC 3/4] Documentation: move dma-buf documentation to rst
Hello Jani, On 11 August 2016 at 17:17, Jani Nikula wrote: > On Thu, 11 Aug 2016, Sumit Semwal wrote: >> diff --git a/Documentation/dma-buf/guide.rst >> b/Documentation/dma-buf/guide.rst >> new file mode 100644 >> index ..fd3534fdccb3 >> --- /dev/null >> +++ b/Documentation/dma-buf/guide.rst >> @@ -0,0 +1,503 @@ >> + >> +.. _dma-buf-guide: >> + >> + >> +DMA Buffer Sharing API Guide >> + >> + >> +Sumit Semwal - sumit.semwal at linaro.org, sumits at kernel.org > > Please use the format > > :author: Sumit Semwal > Thanks very much for reviewing! > --- > > While on this subject, please excuse me for hijacking the thread a bit. > > Personally, I believe it would be better to leave out authorship notes > from documentation and source files in collaborative projects. Of > course, it is only fair that people who deserve credit get the > credit. Listing the authors in the file is often the natural thing to > do, and superficially seems fair. > > However, when do you add more names to the list? When has someone > contributed enough to warrant that? Is it fair that the original authors > keep getting the credit for the contributions of others? After a while, > perhaps there is next to nothing left of the original contributions, but > the bar is really high for removing anyone from the authors. Listing the > authors gives the impression this is *their* file, while everyone should > feel welcome to contribute, and everyone who contributes should feel > ownership. > > IMHO we would be better off using just the git history for the credits. > :) - I totally agree with your stand; this patch was an (almost) direct conversion from the earlier format, hence this patch. But yes, I will remove it in the next iteration. > > BR, > Jani. > > BR, Sumit. > PS. I am no saint here, I've got a couple of authors lines myself. I > promise not to add more. I certainly won't chastise anyone for adding > theirs. > > > -- > Jani Nikula, Intel Open Source Technology Center -- Thanks and regards, Sumit Semwal Linaro Mobile Group - Kernel Team Lead Linaro.org â Open source software for ARM SoCs
[RFC 3/4] Documentation: move dma-buf documentation to rst
Branch out dma-buf related documentation into its own rst file to allow adding it to the sphinx documentation generated. While at it, move dma-buf-sharing.txt into rst as the dma-buf guide too. Signed-off-by: Sumit Semwal --- Documentation/DocBook/device-drivers.tmpl | 37 --- Documentation/dma-buf/guide.rst | 503 ++ Documentation/dma-buf/intro.rst | 76 + MAINTAINERS | 2 +- 4 files changed, 580 insertions(+), 38 deletions(-) create mode 100644 Documentation/dma-buf/guide.rst create mode 100644 Documentation/dma-buf/intro.rst diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 99cdc05bbb7a..a93fbffa9742 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -128,43 +128,6 @@ X!Edrivers/base/interface.c !Edrivers/base/platform.c !Edrivers/base/bus.c - - Buffer Sharing and Synchronization - - The dma-buf subsystem provides the framework for sharing buffers - for hardware (DMA) access across multiple device drivers and - subsystems, and for synchronizing asynchronous hardware access. - - - This is used, for example, by drm "prime" multi-GPU support, but - is of course not limited to GPU use cases. - - - The three main components of this are: (1) dma-buf, representing - a sg_table and exposed to userspace as a file descriptor to allow - passing between devices, (2) fence, which provides a mechanism - to signal when one device as finished access, and (3) reservation, - which manages the shared or exclusive fence(s) associated with - the buffer. - - dma-buf -!Edrivers/dma-buf/dma-buf.c -!Iinclude/linux/dma-buf.h - - reservation -!Pdrivers/dma-buf/reservation.c Reservation Object Overview -!Edrivers/dma-buf/reservation.c -!Iinclude/linux/reservation.h - - fence -!Edrivers/dma-buf/fence.c -!Iinclude/linux/fence.h -!Edrivers/dma-buf/seqno-fence.c -!Iinclude/linux/seqno-fence.h -!Edrivers/dma-buf/sync_file.c -!Iinclude/linux/sync_file.h - - Device Drivers DMA Management !Edrivers/base/dma-coherent.c !Edrivers/base/dma-mapping.c diff --git a/Documentation/dma-buf/guide.rst b/Documentation/dma-buf/guide.rst new file mode 100644 index ..fd3534fdccb3 --- /dev/null +++ b/Documentation/dma-buf/guide.rst @@ -0,0 +1,503 @@ + +.. _dma-buf-guide: + + +DMA Buffer Sharing API Guide + + +Sumit Semwal - sumit.semwal at linaro.org, sumits at kernel.org + +This document serves as a guide to device-driver writers on what is the dma-buf +buffer sharing API, how to use it for exporting and using shared buffers. + +Any device driver which wishes to be a part of DMA buffer sharing, can do so as +either the 'exporter' of buffers, or the 'user' of buffers. + +Say a driver A wants to use buffers created by driver B, then we call B as the +exporter, and A as buffer-user. + +The exporter + +* implements and manages operations for the buffer via + :c:type:`struct dma_buf_ops ` +* allows other users to share the buffer by using dma_buf sharing APIs, +* manages the details of buffer allocation, +* decides about the actual backing storage where this allocation happens, +* takes care of any migration of scatterlist - for all (shared) users of this + buffer, + +The buffer-user + +* is one of (many) sharing users of the buffer. +* doesn't need to worry about how the buffer is allocated, or where. +* needs a mechanism to get access to the scatterlist that makes up this buffer + in memory, mapped into its own address space, so it can access the same area + of memory. + +dma-buf operations for device dma only +== + +The dma_buf buffer sharing API usage contains the following steps: + +1. Exporter announces that it wishes to export a buffer +2. Userspace gets the file descriptor associated with the exported buffer, and + passes it around to potential buffer-users based on use case +3. Each buffer-user 'connects' itself to the buffer +4. When needed, buffer-user requests access to the buffer from exporter +5. When finished with its use, the buffer-user notifies end-of-DMA to exporter +6. when buffer-user is done using this buffer completely, it 'disconnects' + itself from the buffer. + + +1. Exporter's announcement of buffer export +--- + + The buffer exporter announces its wish to export a buffer. In this, it + connects its own private buffer data, provides implementation for operations + that can be performed on the exported :c:type:`dma_buf`, and flags for the file + associated with this buffer. All these fields are filled in struct + :c:type:`dma_buf_export_info`, defined via the
[RFC 3/4] Documentation: move dma-buf documentation to rst
On Thu, 11 Aug 2016, Sumit Semwal wrote: > diff --git a/Documentation/dma-buf/guide.rst b/Documentation/dma-buf/guide.rst > new file mode 100644 > index ..fd3534fdccb3 > --- /dev/null > +++ b/Documentation/dma-buf/guide.rst > @@ -0,0 +1,503 @@ > + > +.. _dma-buf-guide: > + > + > +DMA Buffer Sharing API Guide > + > + > +Sumit Semwal - sumit.semwal at linaro.org, sumits at kernel.org Please use the format :author: Sumit Semwal --- While on this subject, please excuse me for hijacking the thread a bit. Personally, I believe it would be better to leave out authorship notes from documentation and source files in collaborative projects. Of course, it is only fair that people who deserve credit get the credit. Listing the authors in the file is often the natural thing to do, and superficially seems fair. However, when do you add more names to the list? When has someone contributed enough to warrant that? Is it fair that the original authors keep getting the credit for the contributions of others? After a while, perhaps there is next to nothing left of the original contributions, but the bar is really high for removing anyone from the authors. Listing the authors gives the impression this is *their* file, while everyone should feel welcome to contribute, and everyone who contributes should feel ownership. IMHO we would be better off using just the git history for the credits. BR, Jani. PS. I am no saint here, I've got a couple of authors lines myself. I promise not to add more. I certainly won't chastise anyone for adding theirs. -- Jani Nikula, Intel Open Source Technology Center
[RFC 3/4] Documentation: move dma-buf documentation to rst
Am 11.08.2016 um 13:58 schrieb Markus Heiser : >> +.. note:: Until this stage, the buffer-exporter has the option to choose >> not to >> + actually allocate the backing storage for this buffer, but wait for the >> + first buffer-user to request use of buffer for allocation. > > Use newlines ... which are markups in reST ;) > > .. note:: > > Until this stage, the buffer-exporter has the option to choose not to > actually allocate the backing storage for this buffer, but wait for the > first buffer-user to request use of buffer for allocation. > Sorry, my f... apple mail drops leading whitespaces ... |.. note:: | | Until this stage, the buffer-exporter has the option to choose not to | actually allocate the backing storage for this buffer, but wait for the >> +Kernel cpu access to a dma-buf buffer object >> + >> + >> +The motivation to allow cpu access from the kernel to a dma-buf object from >> the >> +importers side are: >> + >> +* fallback operations, e.g. if the devices is connected to a usb bus and the >> + kernel needs to shuffle the data around first before sending it away. >> +* full transparency for existing users on the importer side, i.e. userspace >> + should not notice the difference between a normal object from that >> subsystem >> + and an imported one backed by a dma-buf. This is really important for drm >> + opengl drivers that expect to still use all the existing upload/download >> + paths. > > I is recommended to separate blocks (in this case the list item blocks) with > a newline. E.g. > > * first lorem > ipsum > > * second lorem > ipsum > > If you have only one-liners, it is OK to write > > * first > * second > same here, leading whitespace are droped by the mail client. |* first lorem | ipsum | |* second lorem | ipsum Sorry for disorientation. For a snatch I forgot, that that Apple & MS have a mistaken idea of "plain text" ;) -- Markus --
[RFC 3/4] Documentation: move dma-buf documentation to rst
Hi Sumit, I haven't compiled your patch yet, just my 2cent about the reStructuredText (reST) ASCII markup ... Here are some handy links about reST and the Sphinx markup constructs, we have not yet added to the documentation (sorry): * reST primer:http://www.sphinx-doc.org/en/stable/rest.html * reST quickref: http://docutils.sourceforge.net/docs/user/rst/quickref.html * Sphinx markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html * Sphinx domains: http://www.sphinx-doc.org/en/stable/domains.html * Sphinx cross references: http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations Am 11.08.2016 um 12:47 schrieb Sumit Semwal : > Branch out dma-buf related documentation into its own rst file to allow > adding it to the sphinx documentation generated. > > While at it, move dma-buf-sharing.txt into rst as the dma-buf guide too. > > Signed-off-by: Sumit Semwal ... > +dma-buf operations for device dma only > +== > + > +The dma_buf buffer sharing API usage contains the following steps: > + > +1. Exporter announces that it wishes to export a buffer > +2. Userspace gets the file descriptor associated with the exported buffer, > and > + passes it around to potential buffer-users based on use case > +3. Each buffer-user 'connects' itself to the buffer > +4. When needed, buffer-user requests access to the buffer from exporter > +5. When finished with its use, the buffer-user notifies end-of-DMA to > exporter > +6. when buffer-user is done using this buffer completely, it 'disconnects' > + itself from the buffer. > + > + > +1. Exporter's announcement of buffer export > +--- I can't recommend numbering the (sub-) sections explicit, even if you here wanted to numerate the steps. Most often section numbers are controlled by the subordinate toctree directive and this might not fit to the step numbers. * http://www.sphinx-doc.org/en/stable/markup/toctree.html?highlight=toc#the-toc-tree > + > + The buffer exporter announces its wish to export a buffer. In this, it > + connects its own private buffer data, provides implementation for > operations > + that can be performed on the exported :c:type:`dma_buf`, and flags for > the file > + associated with this buffer. All these fields are filled in struct > + :c:type:`dma_buf_export_info`, defined via the DEFINE_DMA_BUF_EXPORT_INFO > macro. > + In restructuredText whitespace are markups. Do not indent if you don't want to create a (indented) block. I recommend to drop the two spaces in front of the paragraphs. IMHO you have to decide if you like to use sectioning (drop the to spaces) or stay with the two spaces and use an enumeration list. If you wan't to stay with the enumeration write: |1. Exporter's announcement of buffer export | | The buffer exporter announces its wish to export a buffer. In this, it | connects its own private buffer .. | ... > + Interface: > + :c:type:`DEFINE_DMA_BUF_EXPORT_INFO(exp_info) > ` If haven't tested your patch, but I guess this will result in a Warning. the markup ":c:type" is a reference to a typedef description * http://www.sphinx-doc.org/en/stable/domains.html#role-c:type If the description is given, you can use the short form :c:type:`DEFINE_DMA_BUF_EXPORT_INFO` but I think, this is a function, not a typedef. > + > + :c:func:`struct dma_buf *dma_buf_export(struct dma_buf_export_info > *exp_info)` short form to refer :c:func:`dma_buf_export()` > + > + If this succeeds, dma_buf_export allocates a dma_buf structure, and > + returns a pointer to the same. It also associates an anonymous file with > this > + buffer, so it can be exported. On failure to allocate the dma_buf object, > + it returns NULL. > + > + 'exp_name' in struct dma_buf_export_info is the name of exporter - to > + facilitate information while debugging. It is set to KBUILD_MODNAME by If you want to render a constant in a monospace font you can use the inline markup ``KBUILD_MODNAME``, but if you want. > + default, so exporters don't have to provide a specific name, if they don't > + wish to. > + > + DEFINE_DMA_BUF_EXPORT_INFO macro defines the struct dma_buf_export_info, > + zeroes it out and pre-populates exp_name in it. > + > +2. Userspace gets a handle to pass around to potential buffer-users > +--- > + > + Userspace entity requests for a file-descriptor (fd) which is a handle to > the > + anonymous file associated with the buffer. It can then share the fd with > other > + drivers and/or processes. > + > + Interface: > + :c:func:`int dma_buf_fd(struct dma_buf *dmabuf, int flags) > ` > + > + This API installs an fd for the anonymous file associated with this > buffer; > + returns either 'fd', or error. I recommend to markup source code objects uniform with
