[PATCH v3 09/17] docs: core-api: document the IOVA-based API

[anish kumar]

On Sun, Nov 10, 2024 at 6:58 PM Jonathan Corbet <corbet at lwn.net> wrote:
>
> anish kumar <yesanishhere at gmail.com> writes:
>
> > On Sun, Nov 10, 2024 at 5:50 AM Leon Romanovsky <leon at kernel.org> wrote:
> >>
> >> From: Christoph Hellwig <hch at lst.de>
> >>
> >> Add an explanation of the newly added IOVA-based mapping API.
> >>
> >> Signed-off-by: Christoph Hellwig <hch at lst.de>
> >> Signed-off-by: Leon Romanovsky <leonro at nvidia.com>
> >> ---
> >>  Documentation/core-api/dma-api.rst | 70 ++++++++++++++++++++++++++++++
> >>  1 file changed, 70 insertions(+)
> >>
> >> diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
> >> index 8e3cce3d0a23..61d6f4fe3d88 100644
> >> --- a/Documentation/core-api/dma-api.rst
> >> +++ b/Documentation/core-api/dma-api.rst
> >> @@ -530,6 +530,76 @@ routines, e.g.:::
> >>                 ....
> >>         }
> >>
> >> +Part Ie - IOVA-based DMA mappings
> >> +---------------------------------
> >> +
> >> +These APIs allow a very efficient mapping when using an IOMMU.  They are an
> >
> > "They" doesn't sound nice.
> >> +optional path that requires extra code and are only recommended for drivers
> >> +where DMA mapping performance, or the space usage for storing the DMA addresses
> >> +matter.  All the considerations from the previous section apply here as well.
> >
> > These APIs provide an efficient mapping when using an IOMMU. However, they
> > are optional and require additional code. They are recommended primarily for
> > drivers where performance in DMA mapping or the storage space for DMA
> > addresses are critical. All the considerations discussed in the previous section
> > also apply in this case.
> >
> > You can disregard this comment, as anyone reading this paragraph will
> > understand the intended message.
>
> I don't understand the comment, honestly.  You say "they" doesn't "sound
> nice", whatever that means, but your suggestion retains the "they"...?
>
> I'm all for reviews that improve our documentation, but it is
> *incredibly* easy to fall into the trivial bikeshed mode.  I've
> certainly done it myself.  The end result is less documentation as
> people decide, understandably, that it's not worth the pain.  Hopefully
> we can all try to do a bit less of that.
>
> FWIW, I think the paragraph is fine as written.

I completely agree, and that's why I suggested feeling free to disregard
the comment. When I read it, I felt it could be improved, but I
agree—there's no point in overanalyzing it.
>
> Thanks,
>
> jon