Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753297AbcD1NsZ (ORCPT ); Thu, 28 Apr 2016 09:48:25 -0400 Received: from mail-yw0-f196.google.com ([209.85.161.196]:36579 "EHLO mail-yw0-f196.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752685AbcD1NsW (ORCPT ); Thu, 28 Apr 2016 09:48:22 -0400 From: Gustavo Padovan To: Greg Kroah-Hartman Cc: linux-kernel@vger.kernel.org, devel@driverdev.osuosl.org, dri-devel@lists.freedesktop.org, Daniel Stone , =?UTF-8?q?Arve=20Hj=C3=B8nnev=C3=A5g?= , Riley Andrews , Daniel Vetter , Rob Clark , Greg Hackmann , John Harrison , Maarten Lankhorst , Sumit Semwal , Gustavo Padovan Subject: [PATCH v2 13/13] Documentation: add Sync File doc Date: Thu, 28 Apr 2016 10:47:00 -0300 Message-Id: <1461851220-1583-14-git-send-email-gustavo@padovan.org> X-Mailer: git-send-email 2.5.5 In-Reply-To: <1461851220-1583-1-git-send-email-gustavo@padovan.org> References: <1461851220-1583-1-git-send-email-gustavo@padovan.org> Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 3267 Lines: 86 From: Gustavo Padovan Add sync_file documentation on dma-buf-sync_file.txt Reviewed-by: Daniel Vetter --- Documentation/sync_file.txt | 69 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 Documentation/sync_file.txt diff --git a/Documentation/sync_file.txt b/Documentation/sync_file.txt new file mode 100644 index 0000000..eaf8297 --- /dev/null +++ b/Documentation/sync_file.txt @@ -0,0 +1,69 @@ + Sync File API Guide + ~~~~~~~~~~~~~~~~~~~ + + Gustavo Padovan + + +This document serves as a guide for device drivers writers on what the +sync_file API is, and how drivers can support it. Sync file is the carrier of +the fences(struct fence) that needs to synchronized between drivers or across +process boundaries. + +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 a GPU or V4L +driver) sends the fence related to the buffer to userspace via a sync_file. + +The sync_file then can be sent to the consumer (DRM driver for example), that +will not use the buffer for anything before the fence(s) 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 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 an create out-fence 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(struct fence *fence); + +The caller pass 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