Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1460390 > unrolled thread

[RFC 0/4] doc: dma-buf: sphinx conversion and cleanup

Back to article view | Back to linux.kernel

Contents

  [RFC 0/4] doc: dma-buf: sphinx conversion and cleanup  Sumit Semwal <sumit.semwal@linaro.org> - 2016-08-11 12:50 +0200
    [RFC 1/4] dma-buf/fence: kerneldoc: remove unused struct members Sumit Semwal <sumit.semwal@linaro.org> - 2016-08-11 12:50 +0200
    [RFC 2/4] dma-buf/fence: kerneldoc: remove spurious section header Sumit Semwal <sumit.semwal@linaro.org> - 2016-08-11 12:50 +0200
      Re: [RFC 2/4] dma-buf/fence: kerneldoc: remove spurious section  header Daniel Vetter <daniel@ffwll.ch> - 2016-08-12 11:00 +0200
    Re: [RFC 0/4] doc: dma-buf: sphinx conversion and cleanup Jonathan Corbet <corbet@lwn.net> - 2016-08-11 16:40 +0200
      Re: [RFC 0/4] doc: dma-buf: sphinx conversion and cleanup Sumit Semwal <sumit.semwal@linaro.org> - 2016-08-12 08:40 +0200
        Re: [RFC 0/4] doc: dma-buf: sphinx conversion and cleanup Daniel Vetter <daniel@ffwll.ch> - 2016-08-12 10:40 +0200

#1460390 — [RFC 0/4] doc: dma-buf: sphinx conversion and cleanup

Convert dma-buf documentation over to sphinx; also cleanup to
address sphinx warnings.

While at that, convert dma-buf-sharing.txt as well, and make it the
dma-buf API guide.

There is no content change yet; only format conversion and creation of
some hyperlinks.

Sumit Semwal (4):
  dma-buf/fence: kerneldoc: remove unused struct members
  dma-buf/fence: kerneldoc: remove spurious section header
  Documentation: move dma-buf documentation to rst
  Documentation/sphinx: link dma-buf rsts

 Documentation/DocBook/device-drivers.tmpl |  37 ---
 Documentation/dma-buf/guide.rst           | 503 ++++++++++++++++++++++++++++++
 Documentation/dma-buf/intro.rst           |  76 +++++
 Documentation/index.rst                   |   2 +
 MAINTAINERS                               |   2 +-
 include/linux/fence.h                     |   4 +-
 6 files changed, 583 insertions(+), 41 deletions(-)
 create mode 100644 Documentation/dma-buf/guide.rst
 create mode 100644 Documentation/dma-buf/intro.rst

-- 
2.7.4

[toc] | [next] | [standalone]

#1460391 — [RFC 1/4] dma-buf/fence: kerneldoc: remove unused struct members

Commit 0431b9065f28ecf6c320fefebe0241620049984f ("staging/android: bring
struct sync_pt back") removed child_list and active_list from struct fence,
but left it in kernel doc. Delete them.

Fixes: 0431b9065f28 ("staging/android: bring struct sync_pt back")

Signed-off-by: Sumit Semwal <sumit.semwal@linaro.org>
---
 include/linux/fence.h | 2 --
 1 file changed, 2 deletions(-)

diff --git a/include/linux/fence.h b/include/linux/fence.h
index 1de1b3f6fb76..5aa95eb886f7 100644
--- a/include/linux/fence.h
+++ b/include/linux/fence.h
@@ -49,8 +49,6 @@ struct fence_cb;
  * @timestamp: Timestamp when the fence was signaled.
  * @status: Optional, only valid if < 0, must be set before calling
  * fence_signal, indicates that the fence has completed with an error.
- * @child_list: list of children fences
- * @active_list: list of active fences
  *
  * the flags member must be manipulated and read using the appropriate
  * atomic ops (bit_*), so taking the spinlock will not be needed most
-- 
2.7.4

[toc] | [prev] | [next] | [standalone]

#1460393 — [RFC 2/4] dma-buf/fence: kerneldoc: remove spurious section header

Commit e941759c74a44d6ac2eed21bb0a38b21fe4559e2 ("fence: dma-buf
cross-device synchronization (v18)") had a spurious kerneldoc section
header that caused Sphinx to complain. Fix it.

Fixes: e941759c74a4 ("fence: dma-buf cross-device synchronization (v18)")

Signed-off-by: Sumit Semwal <sumit.semwal@linaro.org>
---
 include/linux/fence.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/fence.h b/include/linux/fence.h
index 5aa95eb886f7..5de89dab0013 100644
--- a/include/linux/fence.h
+++ b/include/linux/fence.h
@@ -60,7 +60,7 @@ struct fence_cb;
  * implementer of the fence for its own purposes. Can be used in different
  * ways by different fence implementers, so do not rely on this.
  *
- * *) Since atomic bitops are used, this is not guaranteed to be the case.
+ * Since atomic bitops are used, this is not guaranteed to be the case.
  * Particularly, if the bit was set, but fence_signal was called right
  * before this bit was set, it would have been able to set the
  * FENCE_FLAG_SIGNALED_BIT, before enable_signaling was called.
-- 
2.7.4

[toc] | [prev] | [next] | [standalone]

#1461017 — Re: [RFC 2/4] dma-buf/fence: kerneldoc: remove spurious section header

On Thu, Aug 11, 2016 at 04:17:58PM +0530, Sumit Semwal wrote:
> Commit e941759c74a44d6ac2eed21bb0a38b21fe4559e2 ("fence: dma-buf
> cross-device synchronization (v18)") had a spurious kerneldoc section
> header that caused Sphinx to complain. Fix it.
> 
> Fixes: e941759c74a4 ("fence: dma-buf cross-device synchronization (v18)")
> 
> Signed-off-by: Sumit Semwal <sumit.semwal@linaro.org>

On patches 1&2 Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>


> ---
>  include/linux/fence.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/include/linux/fence.h b/include/linux/fence.h
> index 5aa95eb886f7..5de89dab0013 100644
> --- a/include/linux/fence.h
> +++ b/include/linux/fence.h
> @@ -60,7 +60,7 @@ struct fence_cb;
>   * implementer of the fence for its own purposes. Can be used in different
>   * ways by different fence implementers, so do not rely on this.
>   *
> - * *) Since atomic bitops are used, this is not guaranteed to be the case.
> + * Since atomic bitops are used, this is not guaranteed to be the case.
>   * Particularly, if the bit was set, but fence_signal was called right
>   * before this bit was set, it would have been able to set the
>   * FENCE_FLAG_SIGNALED_BIT, before enable_signaling was called.
> -- 
> 2.7.4
> 
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

[toc] | [prev] | [next] | [standalone]

#1460578

On Thu, 11 Aug 2016 16:17:56 +0530
Sumit Semwal <sumit.semwal@linaro.org> wrote:

> Convert dma-buf documentation over to sphinx; also cleanup to
> address sphinx warnings.
> 
> While at that, convert dma-buf-sharing.txt as well, and make it the
> dma-buf API guide.

Thanks for working to improve the documentation!  I do have a few overall
comments...

 - The two comment fixes are a separate thing that should go straight to
   the dma-buf maintainer, who is ... <looks> ... evidently somebody
   familiar to you :)  I assume you'll merge those two directly?

 - It looks like you create a new RST document but leave the old one in
   place.  Having two copies of the document around can only lead to
   confusion, so I think the old one should go.

 - I really wonder if we want to start carving pieces out of
   device-drivers.tmpl in this way.  I guess I would rather see the
   conversion of that book and the better integration of the other docs
   *into* it.  One of the goals of this whole thing is to unify our
   documentation, not to reinforce the silos.

Does that make sense?

Thanks,

jon

[toc] | [prev] | [next] | [standalone]

#1460970

Hi Jon!

On 11 August 2016 at 20:06, Jonathan Corbet <corbet@lwn.net> wrote:
> On Thu, 11 Aug 2016 16:17:56 +0530
> Sumit Semwal <sumit.semwal@linaro.org> wrote:
>
>> Convert dma-buf documentation over to sphinx; also cleanup to
>> address sphinx warnings.
>>
>> While at that, convert dma-buf-sharing.txt as well, and make it the
>> dma-buf API guide.
>
> Thanks for working to improve the documentation!  I do have a few overall
> comments...
>
Thank you for your review, and comments; my responses are inline.

>  - The two comment fixes are a separate thing that should go straight to
>    the dma-buf maintainer, who is ... <looks> ... evidently somebody
>    familiar to you :)  I assume you'll merge those two directly?
>
Yes, of course :) - I will merge them directly, and will remove them
from v2 of this series.

>  - It looks like you create a new RST document but leave the old one in
>    place.  Having two copies of the document around can only lead to
>    confusion, so I think the old one should go.
>
Agreed on this as well; will correct it.

>  - I really wonder if we want to start carving pieces out of
>    device-drivers.tmpl in this way.  I guess I would rather see the
>    conversion of that book and the better integration of the other docs
>    *into* it.  One of the goals of this whole thing is to unify our
>    documentation, not to reinforce the silos.
>
I should've mentioned it in the cover letter - my intention of taking
the dma-buf pieces out was to focus on these first while moving to
sphinx.

My proposal would be, if all the device driver section owners could
take the relevant pieces, convert them to sphinx (ironing out warnings
etc in the process), then we can again 'bind' them together into the
device drivers book in rst format.
This breaks the documentation conversion task into manageable pieces
that can be handled independently, and gives everyone flexibility to
work on their schedules.

This should also help in a good technical re-look at the content by
subsystem developers, and make any documentation updates as required.
The beauty of sphinx should allow us this, I think? Just my 2 cents.

> Does that make sense?
>
I do hope that my proposal above finds some merit with everyone.

> Thanks,
>
> jon

BR,
Sumit.

[toc] | [prev] | [next] | [standalone]

#1461009

On Fri, Aug 12, 2016 at 12:05:04PM +0530, Sumit Semwal wrote:
> Hi Jon!
> 
> On 11 August 2016 at 20:06, Jonathan Corbet <corbet@lwn.net> wrote:
> > On Thu, 11 Aug 2016 16:17:56 +0530
> > Sumit Semwal <sumit.semwal@linaro.org> wrote:
> >
> >> Convert dma-buf documentation over to sphinx; also cleanup to
> >> address sphinx warnings.
> >>
> >> While at that, convert dma-buf-sharing.txt as well, and make it the
> >> dma-buf API guide.
> >
> > Thanks for working to improve the documentation!  I do have a few overall
> > comments...
> >
> Thank you for your review, and comments; my responses are inline.
> 
> >  - The two comment fixes are a separate thing that should go straight to
> >    the dma-buf maintainer, who is ... <looks> ... evidently somebody
> >    familiar to you :)  I assume you'll merge those two directly?
> >
> Yes, of course :) - I will merge them directly, and will remove them
> from v2 of this series.
> 
> >  - It looks like you create a new RST document but leave the old one in
> >    place.  Having two copies of the document around can only lead to
> >    confusion, so I think the old one should go.
> >
> Agreed on this as well; will correct it.
> 
> >  - I really wonder if we want to start carving pieces out of
> >    device-drivers.tmpl in this way.  I guess I would rather see the
> >    conversion of that book and the better integration of the other docs
> >    *into* it.  One of the goals of this whole thing is to unify our
> >    documentation, not to reinforce the silos.
> >
> I should've mentioned it in the cover letter - my intention of taking
> the dma-buf pieces out was to focus on these first while moving to
> sphinx.
> 
> My proposal would be, if all the device driver section owners could
> take the relevant pieces, convert them to sphinx (ironing out warnings
> etc in the process), then we can again 'bind' them together into the
> device drivers book in rst format.
> This breaks the documentation conversion task into manageable pieces
> that can be handled independently, and gives everyone flexibility to
> work on their schedules.
> 
> This should also help in a good technical re-look at the content by
> subsystem developers, and make any documentation updates as required.
> The beauty of sphinx should allow us this, I think? Just my 2 cents.

I already tried to trick Sumit into converting the entire
device-drivers.tmpl, but he didn't take the bait ;-)

I think just extracting dma-buf stuff (dma_buf, fence, reservation and all
that) is ok though, it is a fairly stand-alone topic.
-Daniel

> 
> > Does that make sense?
> >
> I do hope that my proposal above finds some merit with everyone.
> 
> > Thanks,
> >
> > jon
> 
> BR,
> Sumit.
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web