From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.5 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,HEADER_FROM_DIFFERENT_DOMAINS,HTML_MESSAGE,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 99B9AC47089 for ; Thu, 27 May 2021 11:12:33 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 562C2601FA for ; Thu, 27 May 2021 11:12:33 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 562C2601FA Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=intel-gfx-bounces@lists.freedesktop.org Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id E3BB96EE77; Thu, 27 May 2021 11:12:32 +0000 (UTC) Received: from mail-lf1-x135.google.com (mail-lf1-x135.google.com [IPv6:2a00:1450:4864:20::135]) by gabe.freedesktop.org (Postfix) with ESMTPS id 7E8466EE7A for ; Thu, 27 May 2021 11:12:32 +0000 (UTC) Received: by mail-lf1-x135.google.com with SMTP id w33so7420386lfu.7 for ; Thu, 27 May 2021 04:12:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=NEpx0mv0zIx0GrKlcnbi7SSZ6s3uwNwuzb7fbvJrHQY=; b=cFuaOm0ZBT0UmJFAJEx9Sn4v2y3ZSbjLj8Ek9Oo0lSVT1FPuHzXk+5RkXmSSNcyBxL 4KUK/XSZgXl6X0CohxieWKHEGewTfGOxPSNZNiBGj/4SXk8pMyMwyOQm2BbVPYIMHSGi Dsdm97BOt0tttX3YKMIBItkDeIHms8Hm605WI6tY4YKShFcQGhQy31c3fuplderQ27eQ P8DIofUdYACdPQBZEKKyYmL+2adTh744dvPiIWR/RMCfRB76TrDiFHnthzLqWOeP+2de /auE6ckHPnPgdM2LeufwXATQEYyzGXddC5RQhjIctsM5z0E27OCSS9svJoBhSDE/0OBH hiNw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=NEpx0mv0zIx0GrKlcnbi7SSZ6s3uwNwuzb7fbvJrHQY=; b=VTpJh3OuvsXjMGs4XQu2oZ+1SkhK9oe5LBgn0Gs0iM/hcKH4tMVEnNoUr46UK+dYbb a0MiztSEjY+iJRwsXjb790rMP6UxsopjL9QwH4js9+ox3dazOuMpJtrmFmMzDe1ntNoY UXnGmS3d1+RT0SrZSt0Ah3Vf9vZKZiRP5BXwFlp13ND8Pidsdfqb00dLil2RmVq25VTg KAsVPr14Mjj5gJ83MA5GjwSWwqZx5W21xKBsgHcyEyX+6optStNyyjggxog8OSaZ1MZN Ey/StkyIeaj+5Ncg45MEoEnSrQkytW/TTViwXm+EQ4G5tQqRTs2w4TFIUIK5WvPq0pdn wwFQ== X-Gm-Message-State: AOAM531o94TyqGhQSeEv2S8SvbwAPVny/CAhMxFYcmUtvZy0VJcFbvCw PmqOdYciP3VOJ8plM4B4ERe+gnlX7n3W2qPfahuAKQ== X-Google-Smtp-Source: ABdhPJzXfdzwWGzCmQAtAvCYd7+pLnvsJwtjGpH8e9hAcT8t8Kw9hReq2ICPnBJAMTNhSicXT71dCG3VyNJEwc+r9jE= X-Received: by 2002:a05:6512:3208:: with SMTP id d8mr1916936lfe.361.1622113950702; Thu, 27 May 2021 04:12:30 -0700 (PDT) MIME-Version: 1.0 References: <20210525211753.1086069-1-jason@jlekstrand.net> <20210525211753.1086069-5-jason@jlekstrand.net> In-Reply-To: From: Sumit Semwal Date: Thu, 27 May 2021 16:42:18 +0530 Message-ID: To: Daniel Vetter Subject: Re: [Intel-gfx] [PATCH 4/7] dma-buf: Document DMA_BUF_IOCTL_SYNC X-BeenThere: intel-gfx@lists.freedesktop.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Intel graphics driver community testing & development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Daniel Vetter , Intel Graphics Development , DRI mailing list , =?UTF-8?Q?Christian_K=C3=B6nig?= Content-Type: multipart/mixed; boundary="===============0906252759==" Errors-To: intel-gfx-bounces@lists.freedesktop.org Sender: "Intel-gfx" --===============0906252759== Content-Type: multipart/alternative; boundary="000000000000d1346005c34dd5ef" --000000000000d1346005c34dd5ef Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Hi Daniel, On Thu, 27 May 2021 at 16:08, Daniel Vetter wrote: > On Tue, May 25, 2021 at 04:17:50PM -0500, Jason Ekstrand wrote: > > This adds a new "DMA Buffer ioctls" section to the dma-buf docs and add= s > > documentation for DMA_BUF_IOCTL_SYNC. > > > > Signed-off-by: Jason Ekstrand > > Cc: Daniel Vetter > > Cc: Christian K=C3=B6nig > > Cc: Sumit Semwal > > We're still missing the doc for the SET_NAME ioctl, but maybe Sumit can b= e > motivated to fix that? > Yes, certainly, I'll cook up a patch and send it soon. > > > --- > > Documentation/driver-api/dma-buf.rst | 8 +++++++ > > include/uapi/linux/dma-buf.h | 32 +++++++++++++++++++++++++++- > > 2 files changed, 39 insertions(+), 1 deletion(-) > > > > diff --git a/Documentation/driver-api/dma-buf.rst > b/Documentation/driver-api/dma-buf.rst > > index 7f37ec30d9fd7..784f84fe50a5e 100644 > > --- a/Documentation/driver-api/dma-buf.rst > > +++ b/Documentation/driver-api/dma-buf.rst > > @@ -88,6 +88,9 @@ consider though: > > - The DMA buffer FD is also pollable, see `Implicit Fence Poll > Support`_ below for > > details. > > > > +- The DMA buffer FD also supports a few dma-buf-specific ioctls, see > > + `DMA Buffer ioctls`_ below for details. > > + > > Basic Operation and Device DMA Access > > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > > > @@ -106,6 +109,11 @@ Implicit Fence Poll Support > > .. kernel-doc:: drivers/dma-buf/dma-buf.c > > :doc: implicit fence polling > > > > +DMA Buffer ioctls > > +~~~~~~~~~~~~~~~~~ > > + > > +.. kernel-doc:: include/uapi/linux/dma-buf.h > > + > > Kernel Functions and Structures Reference > > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > > > diff --git a/include/uapi/linux/dma-buf.h b/include/uapi/linux/dma-buf.= h > > index 7f30393b92c3b..1f67ced853b14 100644 > > --- a/include/uapi/linux/dma-buf.h > > +++ b/include/uapi/linux/dma-buf.h > > @@ -22,8 +22,38 @@ > > > > #include > > > > -/* begin/end dma-buf functions used for userspace mmap. */ > > +/** > > + * struct dma_buf_sync - Synchronize with CPU access. > > + * > > + * When a DMA buffer is accessed from the CPU via mmap, it is not alwa= ys > > + * possible to guarantee coherency between the CPU-visible map and > underlying > > + * memory. To manage coherency, DMA_BUF_IOCTL_SYNC must be used to > bracket > > + * any CPU access to give the kernel the chance to shuffle memory > around if > > + * needed. > > + * > > + * Prior to accessing the map, the client should call DMA_BUF_IOCTL_SY= NC > > s/should/must/ > > > + * with DMA_BUF_SYNC_START and the appropriate read/write flags. Once > the > > + * access is complete, the client should call DMA_BUF_IOCTL_SYNC with > > + * DMA_BUF_SYNC_END and the same read/write flags. > > I think we should make it really clear here that this is _only_ for cache > coherency, and that furthermore if you want coherency with gpu access you > either need to use poll() for implicit sync (link to the relevant section= ) > or handle explicit sync with sync_file (again link would be awesome). > > > + */ > > struct dma_buf_sync { > > + /** > > + * @flags: Set of access flags > > + * > > + * - DMA_BUF_SYNC_START: Indicates the start of a map access > > Bikeshed, but I think the item list format instead of bullet point list > looks neater, e.g. DOC: standard plane properties in drm_plane.c. > > > > + * session. > > + * > > + * - DMA_BUF_SYNC_END: Indicates the end of a map access session. > > + * > > + * - DMA_BUF_SYNC_READ: Indicates that the mapped DMA buffer will > > + * be read by the client via the CPU map. > > + * > > + * - DMA_BUF_SYNC_READ: Indicates that the mapped DMA buffer will > > s/READ/WRITE/ > > > + * be written by the client via the CPU map. > > + * > > + * - DMA_BUF_SYNC_RW: An alias for DMA_BUF_SYNC_READ | > > + * DMA_BUF_SYNC_WRITE. > > + */ > > With the nits addressed: Reviewed-by: Daniel Vetter < > daniel.vetter@ffwll.ch> > > > __u64 flags; > > }; > > > > -- > > 2.31.1 > > > > -- > Daniel Vetter > Software Engineer, Intel Corporation > http://blog.ffwll.ch > Best, Sumit. --=20 Thanks and regards, Sumit Semwal Tech Lead - Android, Vertical Technologies Linaro.org =E2=94=82 Open source software for ARM SoCs --000000000000d1346005c34dd5ef Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Hi Daniel,

On Thu, 27 May 2021 at 16:08, D= aniel Vetter <daniel@ffwll.ch>= wrote:
On Tue, = May 25, 2021 at 04:17:50PM -0500, Jason Ekstrand wrote:
> This adds a new "DMA Buffer ioctls" section to the dma-buf d= ocs and adds
> documentation for DMA_BUF_IOCTL_SYNC.
>
> Signed-off-by: Jason Ekstrand <jason@jlekstrand.net>
> Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
> Cc: Christian K=C3=B6nig <christian.koenig@amd.com>
> Cc: Sumit Semwal <sumit.semwal@linaro.org>

We're still missing the doc for the SET_NAME ioctl, but maybe Sumit can= be
motivated to fix that?

Yes, certainly, = I'll cook up a patch and send it soon.=C2=A0

> ---
>=C2=A0 Documentation/driver-api/dma-buf.rst |=C2=A0 8 +++++++
>=C2=A0 include/uapi/linux/dma-buf.h=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0| = 32 +++++++++++++++++++++++++++-
>=C2=A0 2 files changed, 39 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driv= er-api/dma-buf.rst
> index 7f37ec30d9fd7..784f84fe50a5e 100644
> --- a/Documentation/driver-api/dma-buf.rst
> +++ b/Documentation/driver-api/dma-buf.rst
> @@ -88,6 +88,9 @@ consider though:
>=C2=A0 - The DMA buffer FD is also pollable, see `Implicit Fence Poll S= upport`_ below for
>=C2=A0 =C2=A0 details.
>=C2=A0
> +- The DMA buffer FD also supports a few dma-buf-specific ioctls, see<= br> > +=C2=A0 `DMA Buffer ioctls`_ below for details.
> +
>=C2=A0 Basic Operation and Device DMA Access
>=C2=A0 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>=C2=A0
> @@ -106,6 +109,11 @@ Implicit Fence Poll Support
>=C2=A0 .. kernel-doc:: drivers/dma-buf/dma-buf.c
>=C2=A0 =C2=A0 =C2=A0:doc: implicit fence polling
>=C2=A0
> +DMA Buffer ioctls
> +~~~~~~~~~~~~~~~~~
> +
> +.. kernel-doc:: include/uapi/linux/dma-buf.h
> +
>=C2=A0 Kernel Functions and Structures Reference
>=C2=A0 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>=C2=A0
> diff --git a/include/uapi/linux/dma-buf.h b/include/uapi/linux/dma-buf= .h
> index 7f30393b92c3b..1f67ced853b14 100644
> --- a/include/uapi/linux/dma-buf.h
> +++ b/include/uapi/linux/dma-buf.h
> @@ -22,8 +22,38 @@
>=C2=A0
>=C2=A0 #include <linux/types.h>
>=C2=A0
> -/* begin/end dma-buf functions used for userspace mmap. */
> +/**
> + * struct dma_buf_sync - Synchronize with CPU access.
> + *
> + * When a DMA buffer is accessed from the CPU via mmap, it is not alw= ays
> + * possible to guarantee coherency between the CPU-visible map and un= derlying
> + * memory.=C2=A0 To manage coherency, DMA_BUF_IOCTL_SYNC must be used= to bracket
> + * any CPU access to give the kernel the chance to shuffle memory aro= und if
> + * needed.
> + *
> + * Prior to accessing the map, the client should call DMA_BUF_IOCTL_S= YNC

s/should/must/

> + * with DMA_BUF_SYNC_START and the appropriate read/write flags.=C2= =A0 Once the
> + * access is complete, the client should call DMA_BUF_IOCTL_SYNC with=
> + * DMA_BUF_SYNC_END and the same read/write flags.

I think we should make it really clear here that this is _only_ for cache coherency, and that furthermore if you want coherency with gpu access you either need to use poll() for implicit sync (link to the relevant section)<= br> or handle explicit sync with sync_file (again link would be awesome).

> + */
>=C2=A0 struct dma_buf_sync {
> +=C2=A0 =C2=A0 =C2=A0/**
> +=C2=A0 =C2=A0 =C2=A0 * @flags: Set of access flags
> +=C2=A0 =C2=A0 =C2=A0 *
> +=C2=A0 =C2=A0 =C2=A0 * - DMA_BUF_SYNC_START: Indicates the start of a= map access

Bikeshed, but I think the item list format instead of bullet point list
looks neater, e.g.=C2=A0 DOC: standard plane properties in drm_plane.c.


> +=C2=A0 =C2=A0 =C2=A0 *=C2=A0 =C2=A0session.
> +=C2=A0 =C2=A0 =C2=A0 *
> +=C2=A0 =C2=A0 =C2=A0 * - DMA_BUF_SYNC_END: Indicates the end of a map= access session.
> +=C2=A0 =C2=A0 =C2=A0 *
> +=C2=A0 =C2=A0 =C2=A0 * - DMA_BUF_SYNC_READ: Indicates that the mapped= DMA buffer will
> +=C2=A0 =C2=A0 =C2=A0 *=C2=A0 =C2=A0be read by the client via the CPU = map.
> +=C2=A0 =C2=A0 =C2=A0 *
> +=C2=A0 =C2=A0 =C2=A0 * - DMA_BUF_SYNC_READ: Indicates that the mapped= DMA buffer will

s/READ/WRITE/

> +=C2=A0 =C2=A0 =C2=A0 *=C2=A0 =C2=A0be written by the client via the C= PU map.
> +=C2=A0 =C2=A0 =C2=A0 *
> +=C2=A0 =C2=A0 =C2=A0 * - DMA_BUF_SYNC_RW: An alias for DMA_BUF_SYNC_R= EAD |
> +=C2=A0 =C2=A0 =C2=A0 *=C2=A0 =C2=A0DMA_BUF_SYNC_WRITE.
> +=C2=A0 =C2=A0 =C2=A0 */

With the nits addressed: Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>

>=C2=A0 =C2=A0 =C2=A0 =C2=A0__u64 flags;
>=C2=A0 };
>=C2=A0
> --
> 2.31.1
>

--
Daniel Vetter
Software Engineer, Intel Corporation
http:= //blog.ffwll.ch

Best,
Sumit.
--
= Thanks and regards,

Sumit Semwal
Tech Lead - Android, Vertical Te= chnologies
Linaro.org =E2=94=82 Open source software for ARM SoCs
<= /div>
--000000000000d1346005c34dd5ef-- --===============0906252759== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx --===============0906252759==-- From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.5 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,HEADER_FROM_DIFFERENT_DOMAINS,HTML_MESSAGE,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 93AC1C4708A for ; Thu, 27 May 2021 11:12:34 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 598FD601FA for ; Thu, 27 May 2021 11:12:34 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 598FD601FA Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=dri-devel-bounces@lists.freedesktop.org Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id A7C0D6EE7C; Thu, 27 May 2021 11:12:33 +0000 (UTC) Received: from mail-lf1-x134.google.com (mail-lf1-x134.google.com [IPv6:2a00:1450:4864:20::134]) by gabe.freedesktop.org (Postfix) with ESMTPS id 6B0126EE77 for ; Thu, 27 May 2021 11:12:32 +0000 (UTC) Received: by mail-lf1-x134.google.com with SMTP id a5so6675702lfm.0 for ; Thu, 27 May 2021 04:12:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=NEpx0mv0zIx0GrKlcnbi7SSZ6s3uwNwuzb7fbvJrHQY=; b=cFuaOm0ZBT0UmJFAJEx9Sn4v2y3ZSbjLj8Ek9Oo0lSVT1FPuHzXk+5RkXmSSNcyBxL 4KUK/XSZgXl6X0CohxieWKHEGewTfGOxPSNZNiBGj/4SXk8pMyMwyOQm2BbVPYIMHSGi Dsdm97BOt0tttX3YKMIBItkDeIHms8Hm605WI6tY4YKShFcQGhQy31c3fuplderQ27eQ P8DIofUdYACdPQBZEKKyYmL+2adTh744dvPiIWR/RMCfRB76TrDiFHnthzLqWOeP+2de /auE6ckHPnPgdM2LeufwXATQEYyzGXddC5RQhjIctsM5z0E27OCSS9svJoBhSDE/0OBH hiNw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=NEpx0mv0zIx0GrKlcnbi7SSZ6s3uwNwuzb7fbvJrHQY=; b=szeNBNu7x8+oqsWu3RSXobAfEQ1Je7+X+KVEHchnTnO1N4TqLlwkdh6BtNGmiCEzeF kRcv2u/Qy9gwRp8Gx+MLAL3ahC3VWGQQnRqE5bB8Xf2pGis1AKnqTCuN2GPqZ4r9JiEn 2Wj6yvxo//cTKk51Vuy841Y0a/o95soNLBrT5FY8JlNE6FJlAcxjgAuJ2C5/f39TQp9k ZsVTBYGuPJCpQmENp+bkR/+MlmY8hHp+vR1lqY94VvoQXYGF74547cRiE2qg7wgau2eE jNTj1VvvzWoP0ru5NJvZyrSCgfQwIr7tDOBgIYViknqMDTjTWlFuVhMNDPYAW2qblgA3 4IQQ== X-Gm-Message-State: AOAM533pH86f1ChtGhQnI7+kxJ36dMNBLNDZZ3tPneV6szSGkBQ5XjD1 qTY+ps/7pG1vvmDfYkFKvnlLGMKq/7GnaotT0Lc4dQ== X-Google-Smtp-Source: ABdhPJzXfdzwWGzCmQAtAvCYd7+pLnvsJwtjGpH8e9hAcT8t8Kw9hReq2ICPnBJAMTNhSicXT71dCG3VyNJEwc+r9jE= X-Received: by 2002:a05:6512:3208:: with SMTP id d8mr1916936lfe.361.1622113950702; Thu, 27 May 2021 04:12:30 -0700 (PDT) MIME-Version: 1.0 References: <20210525211753.1086069-1-jason@jlekstrand.net> <20210525211753.1086069-5-jason@jlekstrand.net> In-Reply-To: From: Sumit Semwal Date: Thu, 27 May 2021 16:42:18 +0530 Message-ID: Subject: Re: [PATCH 4/7] dma-buf: Document DMA_BUF_IOCTL_SYNC To: Daniel Vetter Content-Type: multipart/alternative; boundary="000000000000d1346005c34dd5ef" X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Daniel Vetter , Intel Graphics Development , DRI mailing list , Jason Ekstrand , =?UTF-8?Q?Christian_K=C3=B6nig?= Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" --000000000000d1346005c34dd5ef Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Hi Daniel, On Thu, 27 May 2021 at 16:08, Daniel Vetter wrote: > On Tue, May 25, 2021 at 04:17:50PM -0500, Jason Ekstrand wrote: > > This adds a new "DMA Buffer ioctls" section to the dma-buf docs and add= s > > documentation for DMA_BUF_IOCTL_SYNC. > > > > Signed-off-by: Jason Ekstrand > > Cc: Daniel Vetter > > Cc: Christian K=C3=B6nig > > Cc: Sumit Semwal > > We're still missing the doc for the SET_NAME ioctl, but maybe Sumit can b= e > motivated to fix that? > Yes, certainly, I'll cook up a patch and send it soon. > > > --- > > Documentation/driver-api/dma-buf.rst | 8 +++++++ > > include/uapi/linux/dma-buf.h | 32 +++++++++++++++++++++++++++- > > 2 files changed, 39 insertions(+), 1 deletion(-) > > > > diff --git a/Documentation/driver-api/dma-buf.rst > b/Documentation/driver-api/dma-buf.rst > > index 7f37ec30d9fd7..784f84fe50a5e 100644 > > --- a/Documentation/driver-api/dma-buf.rst > > +++ b/Documentation/driver-api/dma-buf.rst > > @@ -88,6 +88,9 @@ consider though: > > - The DMA buffer FD is also pollable, see `Implicit Fence Poll > Support`_ below for > > details. > > > > +- The DMA buffer FD also supports a few dma-buf-specific ioctls, see > > + `DMA Buffer ioctls`_ below for details. > > + > > Basic Operation and Device DMA Access > > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > > > @@ -106,6 +109,11 @@ Implicit Fence Poll Support > > .. kernel-doc:: drivers/dma-buf/dma-buf.c > > :doc: implicit fence polling > > > > +DMA Buffer ioctls > > +~~~~~~~~~~~~~~~~~ > > + > > +.. kernel-doc:: include/uapi/linux/dma-buf.h > > + > > Kernel Functions and Structures Reference > > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > > > diff --git a/include/uapi/linux/dma-buf.h b/include/uapi/linux/dma-buf.= h > > index 7f30393b92c3b..1f67ced853b14 100644 > > --- a/include/uapi/linux/dma-buf.h > > +++ b/include/uapi/linux/dma-buf.h > > @@ -22,8 +22,38 @@ > > > > #include > > > > -/* begin/end dma-buf functions used for userspace mmap. */ > > +/** > > + * struct dma_buf_sync - Synchronize with CPU access. > > + * > > + * When a DMA buffer is accessed from the CPU via mmap, it is not alwa= ys > > + * possible to guarantee coherency between the CPU-visible map and > underlying > > + * memory. To manage coherency, DMA_BUF_IOCTL_SYNC must be used to > bracket > > + * any CPU access to give the kernel the chance to shuffle memory > around if > > + * needed. > > + * > > + * Prior to accessing the map, the client should call DMA_BUF_IOCTL_SY= NC > > s/should/must/ > > > + * with DMA_BUF_SYNC_START and the appropriate read/write flags. Once > the > > + * access is complete, the client should call DMA_BUF_IOCTL_SYNC with > > + * DMA_BUF_SYNC_END and the same read/write flags. > > I think we should make it really clear here that this is _only_ for cache > coherency, and that furthermore if you want coherency with gpu access you > either need to use poll() for implicit sync (link to the relevant section= ) > or handle explicit sync with sync_file (again link would be awesome). > > > + */ > > struct dma_buf_sync { > > + /** > > + * @flags: Set of access flags > > + * > > + * - DMA_BUF_SYNC_START: Indicates the start of a map access > > Bikeshed, but I think the item list format instead of bullet point list > looks neater, e.g. DOC: standard plane properties in drm_plane.c. > > > > + * session. > > + * > > + * - DMA_BUF_SYNC_END: Indicates the end of a map access session. > > + * > > + * - DMA_BUF_SYNC_READ: Indicates that the mapped DMA buffer will > > + * be read by the client via the CPU map. > > + * > > + * - DMA_BUF_SYNC_READ: Indicates that the mapped DMA buffer will > > s/READ/WRITE/ > > > + * be written by the client via the CPU map. > > + * > > + * - DMA_BUF_SYNC_RW: An alias for DMA_BUF_SYNC_READ | > > + * DMA_BUF_SYNC_WRITE. > > + */ > > With the nits addressed: Reviewed-by: Daniel Vetter < > daniel.vetter@ffwll.ch> > > > __u64 flags; > > }; > > > > -- > > 2.31.1 > > > > -- > Daniel Vetter > Software Engineer, Intel Corporation > http://blog.ffwll.ch > Best, Sumit. --=20 Thanks and regards, Sumit Semwal Tech Lead - Android, Vertical Technologies Linaro.org =E2=94=82 Open source software for ARM SoCs --000000000000d1346005c34dd5ef Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Hi Daniel,

On Thu, 27 May 2021 at 16:08, D= aniel Vetter <daniel@ffwll.ch>= wrote:
On Tue, = May 25, 2021 at 04:17:50PM -0500, Jason Ekstrand wrote:
> This adds a new "DMA Buffer ioctls" section to the dma-buf d= ocs and adds
> documentation for DMA_BUF_IOCTL_SYNC.
>
> Signed-off-by: Jason Ekstrand <jason@jlekstrand.net>
> Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
> Cc: Christian K=C3=B6nig <christian.koenig@amd.com>
> Cc: Sumit Semwal <sumit.semwal@linaro.org>

We're still missing the doc for the SET_NAME ioctl, but maybe Sumit can= be
motivated to fix that?

Yes, certainly, = I'll cook up a patch and send it soon.=C2=A0

> ---
>=C2=A0 Documentation/driver-api/dma-buf.rst |=C2=A0 8 +++++++
>=C2=A0 include/uapi/linux/dma-buf.h=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0| = 32 +++++++++++++++++++++++++++-
>=C2=A0 2 files changed, 39 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driv= er-api/dma-buf.rst
> index 7f37ec30d9fd7..784f84fe50a5e 100644
> --- a/Documentation/driver-api/dma-buf.rst
> +++ b/Documentation/driver-api/dma-buf.rst
> @@ -88,6 +88,9 @@ consider though:
>=C2=A0 - The DMA buffer FD is also pollable, see `Implicit Fence Poll S= upport`_ below for
>=C2=A0 =C2=A0 details.
>=C2=A0
> +- The DMA buffer FD also supports a few dma-buf-specific ioctls, see<= br> > +=C2=A0 `DMA Buffer ioctls`_ below for details.
> +
>=C2=A0 Basic Operation and Device DMA Access
>=C2=A0 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>=C2=A0
> @@ -106,6 +109,11 @@ Implicit Fence Poll Support
>=C2=A0 .. kernel-doc:: drivers/dma-buf/dma-buf.c
>=C2=A0 =C2=A0 =C2=A0:doc: implicit fence polling
>=C2=A0
> +DMA Buffer ioctls
> +~~~~~~~~~~~~~~~~~
> +
> +.. kernel-doc:: include/uapi/linux/dma-buf.h
> +
>=C2=A0 Kernel Functions and Structures Reference
>=C2=A0 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>=C2=A0
> diff --git a/include/uapi/linux/dma-buf.h b/include/uapi/linux/dma-buf= .h
> index 7f30393b92c3b..1f67ced853b14 100644
> --- a/include/uapi/linux/dma-buf.h
> +++ b/include/uapi/linux/dma-buf.h
> @@ -22,8 +22,38 @@
>=C2=A0
>=C2=A0 #include <linux/types.h>
>=C2=A0
> -/* begin/end dma-buf functions used for userspace mmap. */
> +/**
> + * struct dma_buf_sync - Synchronize with CPU access.
> + *
> + * When a DMA buffer is accessed from the CPU via mmap, it is not alw= ays
> + * possible to guarantee coherency between the CPU-visible map and un= derlying
> + * memory.=C2=A0 To manage coherency, DMA_BUF_IOCTL_SYNC must be used= to bracket
> + * any CPU access to give the kernel the chance to shuffle memory aro= und if
> + * needed.
> + *
> + * Prior to accessing the map, the client should call DMA_BUF_IOCTL_S= YNC

s/should/must/

> + * with DMA_BUF_SYNC_START and the appropriate read/write flags.=C2= =A0 Once the
> + * access is complete, the client should call DMA_BUF_IOCTL_SYNC with=
> + * DMA_BUF_SYNC_END and the same read/write flags.

I think we should make it really clear here that this is _only_ for cache coherency, and that furthermore if you want coherency with gpu access you either need to use poll() for implicit sync (link to the relevant section)<= br> or handle explicit sync with sync_file (again link would be awesome).

> + */
>=C2=A0 struct dma_buf_sync {
> +=C2=A0 =C2=A0 =C2=A0/**
> +=C2=A0 =C2=A0 =C2=A0 * @flags: Set of access flags
> +=C2=A0 =C2=A0 =C2=A0 *
> +=C2=A0 =C2=A0 =C2=A0 * - DMA_BUF_SYNC_START: Indicates the start of a= map access

Bikeshed, but I think the item list format instead of bullet point list
looks neater, e.g.=C2=A0 DOC: standard plane properties in drm_plane.c.


> +=C2=A0 =C2=A0 =C2=A0 *=C2=A0 =C2=A0session.
> +=C2=A0 =C2=A0 =C2=A0 *
> +=C2=A0 =C2=A0 =C2=A0 * - DMA_BUF_SYNC_END: Indicates the end of a map= access session.
> +=C2=A0 =C2=A0 =C2=A0 *
> +=C2=A0 =C2=A0 =C2=A0 * - DMA_BUF_SYNC_READ: Indicates that the mapped= DMA buffer will
> +=C2=A0 =C2=A0 =C2=A0 *=C2=A0 =C2=A0be read by the client via the CPU = map.
> +=C2=A0 =C2=A0 =C2=A0 *
> +=C2=A0 =C2=A0 =C2=A0 * - DMA_BUF_SYNC_READ: Indicates that the mapped= DMA buffer will

s/READ/WRITE/

> +=C2=A0 =C2=A0 =C2=A0 *=C2=A0 =C2=A0be written by the client via the C= PU map.
> +=C2=A0 =C2=A0 =C2=A0 *
> +=C2=A0 =C2=A0 =C2=A0 * - DMA_BUF_SYNC_RW: An alias for DMA_BUF_SYNC_R= EAD |
> +=C2=A0 =C2=A0 =C2=A0 *=C2=A0 =C2=A0DMA_BUF_SYNC_WRITE.
> +=C2=A0 =C2=A0 =C2=A0 */

With the nits addressed: Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>

>=C2=A0 =C2=A0 =C2=A0 =C2=A0__u64 flags;
>=C2=A0 };
>=C2=A0
> --
> 2.31.1
>

--
Daniel Vetter
Software Engineer, Intel Corporation
http:= //blog.ffwll.ch

Best,
Sumit.
--
= Thanks and regards,

Sumit Semwal
Tech Lead - Android, Vertical Te= chnologies
Linaro.org =E2=94=82 Open source software for ARM SoCs
<= /div>
--000000000000d1346005c34dd5ef--