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

[Jonathan Corbet]

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.

Thanks,

jon