From patchwork Wed Apr 27 16:27:19 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Gustavo Padovan X-Patchwork-Id: 8959981 Return-Path: X-Original-To: patchwork-dri-devel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork1.web.kernel.org (Postfix) with ESMTP id E953A9F1C1 for ; Wed, 27 Apr 2016 16:30:53 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 0B8B420219 for ; Wed, 27 Apr 2016 16:30:53 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) by mail.kernel.org (Postfix) with ESMTP id 2C99A2024D for ; Wed, 27 Apr 2016 16:30:51 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 9A92E6EB9A; Wed, 27 Apr 2016 16:30:47 +0000 (UTC) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mail-yw0-f195.google.com (mail-yw0-f195.google.com [209.85.161.195]) by gabe.freedesktop.org (Postfix) with ESMTPS id 2D44F6EB8D for ; Wed, 27 Apr 2016 16:28:26 +0000 (UTC) Received: by mail-yw0-f195.google.com with SMTP id i22so322433ywc.1 for ; Wed, 27 Apr 2016 09:28:26 -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=GRPFXc+228+q2W133v/vlE05mddORxYBz6+heIirimQ=; b=FfqaHZQKX6+KGN8THLApsMBWmY1MPQp8GBPwokyTaoqJIkgnKYNsYNDO6x2AiXEeDw auLs92I0Ebe6EXqJ75ru5xzV5MeN0+cE+sfbawDqyCE9uqJqOgRHt95NKViHHJaeiluJ rfoeIqTzFQnN/zzyLKT6DSlZlWRLMcnlkC+0qSYtXAPg9QJRU/YYp7mXdbueh4y6y/Z0 ercV9my4jEf1XmoubEYAq39yp2OJ/F80J9ykNovec3p7SESVJ/BPkAbNa7WIUtlH8Ll3 SQhvjz7TpHvELTQ5doMvsnaP1TWCtuQC0cfKr4hLUFFBCsbWHCI+ICnJai4KpKhHJC1l pnYA== X-Gm-Message-State: AOPr4FWDvkvcTWwWfI7NixzgirUQngLY2CHy3DRppOmhXVwD4y5PM+hZR6TpqvvyKoRAfA== X-Received: by 10.13.243.5 with SMTP id c5mr6243402ywf.40.1461774504784; Wed, 27 Apr 2016 09:28:24 -0700 (PDT) Received: from jade.localdomain ([201.82.24.203]) by smtp.gmail.com with ESMTPSA id k80sm2308816ywe.31.2016.04.27.09.28.20 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 27 Apr 2016 09:28:24 -0700 (PDT) From: Gustavo Padovan To: Greg Kroah-Hartman 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> 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/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 + + +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