From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S935519AbcJUVKZ (ORCPT ); Fri, 21 Oct 2016 17:10:25 -0400 Received: from tex.lwn.net ([70.33.254.29]:37871 "EHLO vena.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S934925AbcJUVJX (ORCPT ); Fri, 21 Oct 2016 17:09:23 -0400 Date: Fri, 21 Oct 2016 15:09:16 -0600 From: Jonathan Corbet To: Punit Agrawal Cc: linux-doc@vger.kernel.org, will.deacon@arm.com, robin.murphy@arm.com, linux-kernel@vger.kernel.org, linux-arm-kernel@lists.infradead.org, arnd@arndb.de, joro@8bytes.org, dwmw2@infradead.org Subject: Re: [PATCH] Documentation: DMA-API: Clarify semantics of dma_set_mask_and_coherent Message-ID: <20161021150916.0d274e9f@lwn.net> In-Reply-To: <20161017152623.7649-1-punit.agrawal@arm.com> References: <20161017152623.7649-1-punit.agrawal@arm.com> Organization: LWN.net X-Mailer: Claws Mail 3.14.0 (GTK+ 2.24.31; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Mon, 17 Oct 2016 16:26:23 +0100 Punit Agrawal wrote: > The dma mapping api howto gives the impression that using the > dma_set_mask_and_coherent (and related DMA APIs) will cause the kernel > to check all the components in the path from the device to memory for > addressing restrictions. In systems with address translations between > the device and memory (e.g., when using IOMMU), this implies that a > successful call to set set dma mask has checked the addressing > constraints of the intermediaries as well. > > For the IOMMU drivers in the tree, the check is actually performed while > allocating the DMA buffer rather than when the DMA mask is > configured. For MMUs that do not support the full device addressing > capability, the allocations are made from a reduced address space. > > Update the documentation to clarify that even though the call to > dma_set_mask_and_coherent succeeds, it may not be possible to use the > full addressing capability of the device. OK, so I guess I can buy this. But... > Signed-off-by: Punit Agrawal > Cc: Jonathan Corbet > --- > Documentation/DMA-API-HOWTO.txt | 39 +++++++++++++++++++++++---------------- > 1 file changed, 23 insertions(+), 16 deletions(-) > > diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt > index 979228b..240d1ee 100644 > --- a/Documentation/DMA-API-HOWTO.txt > +++ b/Documentation/DMA-API-HOWTO.txt > @@ -159,39 +159,46 @@ support 64-bit addressing (DAC) for all transactions. And at least > one platform (SGI SN2) requires 64-bit consistent allocations to > operate correctly when the IO bus is in PCI-X mode. > > -For correct operation, you must interrogate the kernel in your device > -probe routine to see if the DMA controller on the machine can properly > -support the DMA addressing limitation your device has. It is good > +For correct operation, you must inform the kernel in your device probe > +routine to see if the DMA controller on the machine can properly > +support the DMA addressing capabilities your device has. It is good Here it's still saying "to see if the DMA controller on the machine can properly support the DMA addressing capabilities your device has". So you've not really changed the sense of this sentence here. If I understand things correctly, the calls in question are storing the device's limitations; they will only fail if the kernel is entirely unable to work within the indicated range, right? I don't think there's ever been any guarantee that the system as a whole could use the entire range that is addressable by the device. I have no objection to making that more clear, but let's actually make it more clear by saying what the functions are actually doing. Make sense, or am I missing something here? Thanks, jon