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 F. Padovan" X-Patchwork-Id: 43682 X-Patchwork-Delegate: hverkuil@xs4all.nl Received: from vger.kernel.org ([209.132.180.67]) by www.linuxtv.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dnb7P-0002eG-Ow; Fri, 01 Sep 2017 01:51:36 +0000 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751739AbdIABvd (ORCPT + 1 other); 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 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 ============