From patchwork Thu Apr 28 13:47:00 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Gustavo Padovan X-Patchwork-Id: 8971071 Return-Path: X-Original-To: patchwork-dri-devel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 1D4EBBF29F for ; Thu, 28 Apr 2016 13:48:31 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 32D7820219 for ; Thu, 28 Apr 2016 13:48:30 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) by mail.kernel.org (Postfix) with ESMTP id 447FA2026C for ; Thu, 28 Apr 2016 13:48:27 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 17FD06ED20; Thu, 28 Apr 2016 13:48:25 +0000 (UTC) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mail-yw0-f196.google.com (mail-yw0-f196.google.com [209.85.161.196]) by gabe.freedesktop.org (Postfix) with ESMTPS id F21766ED24 for ; Thu, 28 Apr 2016 13:48:22 +0000 (UTC) Received: by mail-yw0-f196.google.com with SMTP id y6so5029113ywe.0 for ; Thu, 28 Apr 2016 06:48:22 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=FqjApJxra++XaY7FI8XFadkIsi1M1pT90AmkOvq/kYI=; b=Xurel4QdUTA883tpyqP1cEvU1ypFq44MWItTB8oOSGR7k3n6BIhDI4S9OYRWQQJjLT zzzXdMWhEJrb0d9IPqTzIbBcD9eHrrsO4QJkobZg7Vkq0Q79QGgb7BjZx6taRtzw/OwZ aBa+6gBQN6OuM8cJjQRKgfAjbLmnzToM4I0YGnkFa5EGDrpB6qzAoD9uYMgy8XBxsWpg 8T2zxdHa4nZEnlUNVtN4Y3q1guVkb65IMQBmz6edqfQO1qHj/syWeWU/eRttGdW7jaqv X+ntz1uHCRSpZrXyiircf1kRVIkbuB3AXSTgUNtfhFKZ8WvFNyszVJCFsR9Lxk3857bd 65nQ== X-Gm-Message-State: AOPr4FUosARyH/SXcK5JsOSzlEt9eaZg6CE7fyO/9+0+/BnQae+Ucc4DtG7nP/z0Qwh4yw== X-Received: by 10.129.31.212 with SMTP id f203mr7961517ywf.95.1461851301238; Thu, 28 Apr 2016 06:48:21 -0700 (PDT) Received: from jade.localdomain ([201.82.24.203]) by smtp.gmail.com with ESMTPSA id u22sm4722639ywe.28.2016.04.28.06.48.14 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 28 Apr 2016 06:48:20 -0700 (PDT) From: Gustavo Padovan To: Greg Kroah-Hartman 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> Cc: devel@driverdev.osuosl.org, Daniel Stone , Daniel Vetter , Riley Andrews , dri-devel@lists.freedesktop.org, linux-kernel@vger.kernel.org, =?UTF-8?q?Arve=20Hj=C3=B8nnev=C3=A5g?= , Gustavo Padovan , John Harrison X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" X-Spam-Status: No, score=-3.8 required=5.0 tests=BAYES_00, RCVD_IN_BL_SPAMCOP_NET, RCVD_IN_DNSWL_MED, RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP 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