On Sun, Nov 10, 2024 at 6:58 PM Jonathan Corbet <corbet@xxxxxxx> wrote: > > anish kumar <yesanishhere@xxxxxxxxx> writes: > > > On Sun, Nov 10, 2024 at 5:50 AM Leon Romanovsky <leon@xxxxxxxxxx> wrote: > >> > >> From: Christoph Hellwig <hch@xxxxxx> > >> > >> Add an explanation of the newly added IOVA-based mapping API. > >> > >> Signed-off-by: Christoph Hellwig <hch@xxxxxx> > >> Signed-off-by: Leon Romanovsky <leonro@xxxxxxxxxx> > >> --- > >> 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
