Return-Path: <linux-kernel-owner@vger.kernel.org>
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
	id S1753583AbcD0Q22 (ORCPT <rfc822;w@1wt.eu>);
	Wed, 27 Apr 2016 12:28:28 -0400
Received: from mail-yw0-f194.google.com ([209.85.161.194]:35307 "EHLO
	mail-yw0-f194.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org
	with ESMTP id S1752749AbcD0Q2Z (ORCPT
	<rfc822;linux-kernel@vger.kernel.org>);
	Wed, 27 Apr 2016 12:28:25 -0400
From: Gustavo Padovan <gustavo@padovan.org>
To: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: linux-kernel@vger.kernel.org, devel@driverdev.osuosl.org,
        dri-devel@lists.freedesktop.org, Daniel Stone <daniels@collabora.com>,
        =?UTF-8?q?Arve=20Hj=C3=B8nnev=C3=A5g?= <arve@android.com>,
        Riley Andrews <riandrews@android.com>,
        Daniel Vetter <daniel.vetter@ffwll.ch>,
        Rob Clark <robdclark@gmail.com>, Greg Hackmann <ghackmann@google.com>,
        John Harrison <John.C.Harrison@Intel.com>,
        Maarten Lankhorst <maarten.lankhorst@linux.intel.com>,
        Sumit Semwal <sumit.semwal@linaro.org>,
        Gustavo Padovan <gustavo.padovan@collabora.co.uk>
Subject: [PATCH 12/12] Documentation: add Sync File doc
Date: Wed, 27 Apr 2016 13:27:19 -0300
Message-Id: <1461774439-11512-13-git-send-email-gustavo@padovan.org>
X-Mailer: git-send-email 2.5.5
In-Reply-To: <1461774439-11512-1-git-send-email-gustavo@padovan.org>
References: <1461774439-11512-1-git-send-email-gustavo@padovan.org>
Sender: linux-kernel-owner@vger.kernel.org
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org
Content-Length: 3247
Lines: 81

From: Gustavo Padovan <gustavo.padovan@collabora.co.uk>

Add sync_file documentation on dma-buf-sync_file.txt
---
 Documentation/dma-buf-sync_file.txt | 65 +++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 Documentation/dma-buf-sync_file.txt

diff --git a/Documentation/dma-buf-sync_file.txt b/Documentation/dma-buf-sync_file.txt
new file mode 100644
index 0000000..aa7320f
--- /dev/null
+++ b/Documentation/dma-buf-sync_file.txt
@@ -0,0 +1,65 @@
+			 DMA Buffer Sync File API Guide
+			 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+				Gustavo Padovan
+			  <gustavo at padovan dot org>
+
+This document serves as a guide for device drivers writers on what is the
+dma-buf sync_file API, and how drivers can support it. Sync file is the
+carrier of the fences(struct fence) that needs to synchronized between drivers.
+
+The sync_file API is meant to be used to send and receive fence information
+to/from userspace. It enables userspace to do explicit fencing, where instead
+of attaching a fence to the buffer a Producer driver (such as GPU or V4L
+driver) it sends the fence related to the buffer to userspace. The fence then
+can be sent to the Consumer (DRM driver for example), that will not use the
+buffer for anything before the fence signals, i.e., the driver that issued the
+fence is not using/processing the buffer anymore, so it signals that the buffer
+is ready to use. And vice-versa for the Consumer -> Producer part of the cycle.
+Sync files allows userspace awareness on the DMA buffer sharing synchronization
+between drivers.
+
+Sync file was originally added in the Android kernel but current Linux Desktop
+can benefit a lot from it.
+
+in-fences and out-fences
+------------------------
+
+Sync files can go either to or from userspace. When a sync_file is sent from
+the driver to userspace we call the fences it contains 'out-fences'. They are
+related to a buffer that the driver is processing or is going to process, so
+the driver create out-fences to be able to notify, through fence_signal(), when
+it has finished using (or processing) that buffer. Out-fences are fences that
+the driver creates.
+
+On the other hand if the driver receives fence(s) through a sync_file from
+userspace we call these fence(s) 'in-fences'. Receiveing in-fences means that
+we need to wait for the fence(s) to signal before using any buffer related to
+the in-fences.
+
+Creating Sync Files
+-------------------
+
+When a driver needs to send an out-fence userspace it creates a sync_file.
+
+Interface:
+	struct sync_file *sync_file_create(const char *name, struct fence *fence);
+
+The caller pass the name and the out-fence and gets back the sync_file. That is
+just the first step, next it needs to install an fd on sync_file->file. So it
+gets an fd:
+
+	fd = get_unused_fd_flags(O_CLOEXEC);
+
+and installs it on sync_file->file:
+
+	fd_install(fd, sync_file->file);
+
+The sync_file fd now can be sent to userspace.
+
+If the creation process fail, or the sync_file needs to be released by any
+other reason fput(sync_file->file) should be used.
+
+References:
+[1] struct sync_file in include/linux/sync_file.h
+[2] All interfaces mentioned above defined in include/linux/sync_file.h
-- 
2.5.5