From:   Daniel Thompson <daniel.thompson@linaro.org>
To:     Maarten Lankhorst <maarten.lankhorst@linux.intel.com>,
        Maxime Ripard <mripard@kernel.org>,
        Thomas Zimmermann <tzimmermann@suse.de>,
        David Airlie <airlied@linux.ie>,
        Daniel Vetter <daniel@ffwll.ch>
Cc:     Daniel Thompson <daniel.thompson@linaro.org>,
        dri-devel@lists.freedesktop.org, linux-kernel@vger.kernel.org
Subject: [PATCH] drm/cma-helper: Describe what a "contiguous chunk" actually means
Date:   Thu, 16 Dec 2021 17:10:04 +0000
Message-Id: <20211216171004.18166-1-daniel.thompson@linaro.org>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

Since it's inception in 2012 it has been understood that the DRM GEM CMA
helpers do not depend on CMA as the backend allocator. In fact the first
bug fix to ensure the cma-helpers work correctly with an IOMMU backend
appeared in 2014. However currently the documentation for
drm_gem_cma_create() talks about "a contiguous chunk of memory" without
making clear which address space it will be a contiguous part of.
Additionally the CMA introduction is actively misleading because it only
contemplates the CMA backend.

This matters because when the device accesses the bus through an IOMMU
(and don't use the CMA backend) then the allocated memory is contiguous
only in the IOVA space. This is a significant difference compared to the
CMA bankend and the behaviour can be a surprise even to someone who does
a reasonable level of code browsing (but doesn't find all the relevant
function pointers ;-) ).

Improve the kernel doc comments accordingly.

Signed-off-by: Daniel Thompson <daniel.thompson@linaro.org>
---
 drivers/gpu/drm/drm_gem_cma_helper.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/gpu/drm/drm_gem_cma_helper.c b/drivers/gpu/drm/drm_gem_cma_helper.c
index 8467783e92f3..81d7181deebd 100644
--- a/drivers/gpu/drm/drm_gem_cma_helper.c
+++ b/drivers/gpu/drm/drm_gem_cma_helper.c
@@ -32,10 +32,10 @@
  *
  * For devices the access the memory bus through an (external) IOMMU then
  * the buffer objects can be scattered in physical memory but linearized
- * in the IOVA space by the MMU.
+ * in the IOVA space by the IOMMU.
  *
  * For other devices we must rely on the Contiguous Memory Allocator to
- * reserve a pool of memory at early boot that is used to service requests
+ * reserve a pool of memory at early boot. This is then used to service requests
  * for large blocks of physically contiguous memory.
  */


base-commit: 2585cf9dfaaddf00b069673f27bb3f8530e2039c
prerequisite-patch-id: bfcd9122d2546ec77e0bd987663777192002bc91
--
2.34.1