From patchwork Fri Sep 1 01:50:41 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Gustavo Padovan X-Patchwork-Id: 9933311 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id B5FB6602F0 for ; Fri, 1 Sep 2017 01:51:35 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id A881427F7F for ; Fri, 1 Sep 2017 01:51:35 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 9D35427F86; Fri, 1 Sep 2017 01:51:35 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.4 required=2.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, RCVD_IN_SORBS_SPAM autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 3D4F727F7F for ; Fri, 1 Sep 2017 01:51:35 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751739AbdIABvd (ORCPT ); Thu, 31 Aug 2017 21:51:33 -0400 Received: from mail-qk0-f196.google.com ([209.85.220.196]:36702 "EHLO mail-qk0-f196.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751724AbdIABvd (ORCPT ); Thu, 31 Aug 2017 21:51:33 -0400 Received: by mail-qk0-f196.google.com with SMTP id l65so981910qkc.3 for ; Thu, 31 Aug 2017 18:51:33 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=/2rEbf1s7H8d0dfq7oG2T6fnxGTENLlnPrgUysuRWEE=; b=LaCLPc5HjjLYMnvn9jYkjM+/kNGNCvaU5UdTaEnZ144VUQGURWFIEGLe5DIJjBWAFs xnHXzH9hnckzt/I0FlyH3mHkXR935V8pGsfwQ//OKZuyjLhcegAq/WYqwXHLjTmNoTCW oY3UcN3mdflJ8UccAXCxoltZTd/lBtghdrtlqHxlskVJSZGp67k6mJSC7rqRvEC6RIXf j6oXT0RTyRab5FKLlXrWROxaCenx+NMdLFCC72QNSqw2n+4m0dHNOIS4usdtQy6HnNTL hkJVO/xdIJXsr/OT9sAyOI2Ed63HuMJp7ALItP8D0FJj61GeZwAjpMHxfJ2FNUAKx1xO uqwA== X-Gm-Message-State: AHPjjUhJfoWSTb1qHvwSEt33zSng4jvL4+s69rYsAqcbRZH1RPiTbFDq ARUoLn6SJXfNzZJw/Fk= X-Google-Smtp-Source: ADKCNb7uuQPW6aAi0AAnbfT6rydmWXsFEIx+Evx4cFYvUjEqgztIM8PC708mpjhKS0jLCcvcbbm02w== X-Received: by 10.55.16.167 with SMTP id 39mr511162qkq.311.1504230692467; Thu, 31 Aug 2017 18:51:32 -0700 (PDT) Received: from localhost.localdomain ([187.10.21.246]) by smtp.gmail.com with ESMTPSA id o17sm6366232qkl.52.2017.08.31.18.51.29 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 31 Aug 2017 18:51:32 -0700 (PDT) From: Gustavo Padovan To: linux-media@vger.kernel.org Cc: Hans Verkuil , Mauro Carvalho Chehab , Shuah Khan , Gustavo Padovan Subject: [PATCH v2 14/14] [media] v4l: Document explicit synchronization behaviour Date: Thu, 31 Aug 2017 22:50:41 -0300 Message-Id: <20170901015041.7757-15-gustavo@padovan.org> X-Mailer: git-send-email 2.13.5 In-Reply-To: <20170901015041.7757-1-gustavo@padovan.org> References: <20170901015041.7757-1-gustavo@padovan.org> Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Gustavo Padovan Add section to VIDIOC_QBUF about it Signed-off-by: Gustavo Padovan --- Documentation/media/uapi/v4l/vidioc-qbuf.rst | 30 ++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/Documentation/media/uapi/v4l/vidioc-qbuf.rst b/Documentation/media/uapi/v4l/vidioc-qbuf.rst index 1f3612637200..6bd960d3972b 100644 --- a/Documentation/media/uapi/v4l/vidioc-qbuf.rst +++ b/Documentation/media/uapi/v4l/vidioc-qbuf.rst @@ -117,6 +117,36 @@ immediately with an ``EAGAIN`` error code when no buffer is available. The struct :c:type:`v4l2_buffer` structure is specified in :ref:`buffer`. +Explicit Synchronization +------------------------ + +Explicit Synchronization allows us to control the synchronization of +shared buffers from userspace by passing fences to the kernel and/or +receiving them from it. Fences passed to the kernel are named in-fences and +the kernel should wait them to signal before using the buffer, i.e., queueing +it to the driver. On the other side, the kernel can create out-fences for the +buffers it queues to the drivers, out-fences signal when the driver is +finished with buffer, that is the buffer is ready. + +The in-fences and out-fences are communicated at the ``VIDIOC_QBUF`` ioctl +using the ``V4L2_BUF_FLAG_IN_FENCE`` and ``V4L2_BUF_FLAG_OUT_FENCE`` buffer +flags and the `fence_fd` field. If an in-fence needs to be passed to the kernel, +`fence_fd` should be set to the fence file descriptor number and the +``V4L2_BUF_FLAG_IN_FENCE`` should be set as well. + +To get a out-fence back from V4L2 the ``V4L2_BUF_FLAG_OUT_FENCE`` flag should +be set and the `fence_fd` field will be returned with the out-fence file +descriptor related to the next buffer to be queued internally to the V4L2 +driver. That means the out-fence may not be associated with the buffer in the +current ``VIDIOC_QBUF`` ioctl call because the ordering in which videobuf2 core +queues the buffers to the drivers can't be guaranteed. To become aware of the +buffer with which the out-fence will be attached the ``V4L2_EVENT_BUF_QUEUED`` +should be used. It will trigger an event for every buffer queued to the V4L2 +driver. + +Note that the `fence_fd` field is both an input and output argument here with +different meaning on each direction. As input argument it carries an in-fence +and as output argument it carries an out-fence. Return Value ============