From patchwork Tue Jul 5 01:31:05 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 9213417 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 0182A60467 for ; Tue, 5 Jul 2016 01:32:39 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id E468528800 for ; Tue, 5 Jul 2016 01:32:38 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id D8F4F28802; Tue, 5 Jul 2016 01:32:38 +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.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI 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 5678028800 for ; Tue, 5 Jul 2016 01:32:38 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932997AbcGEBcf (ORCPT ); Mon, 4 Jul 2016 21:32:35 -0400 Received: from bombadil.infradead.org ([198.137.202.9]:38627 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754172AbcGEBbZ (ORCPT ); Mon, 4 Jul 2016 21:31:25 -0400 Received: from 201.86.133.99.dynamic.adsl.gvt.net.br ([201.86.133.99] helo=smtp.w2.samsung.com) by bombadil.infradead.org with esmtpsa (Exim 4.85_2 #1 (Red Hat Linux)) id 1bKFCv-0001gg-6p; Tue, 05 Jul 2016 01:31:25 +0000 Received: from mchehab by smtp.w2.samsung.com with local (Exim 4.87) (envelope-from ) id 1bKFCp-0001bp-Ki; Mon, 04 Jul 2016 22:31:19 -0300 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Jonathan Corbet , Markus Heiser , linux-doc@vger.kernel.org Subject: [PATCH 30/41] Documentation: dmabuf.rst: Add ioctl cross references Date: Mon, 4 Jul 2016 22:31:05 -0300 Message-Id: <739012fe35596c42f103bde5cd6acf0a2fa7af5c.1467670142.git.mchehab@s-opensource.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <376f8877e078483e22a906cb0126f8db37bde441.1467670142.git.mchehab@s-opensource.com> References: <376f8877e078483e22a906cb0126f8db37bde441.1467670142.git.mchehab@s-opensource.com> In-Reply-To: <376f8877e078483e22a906cb0126f8db37bde441.1467670142.git.mchehab@s-opensource.com> References: <376f8877e078483e22a906cb0126f8db37bde441.1467670142.git.mchehab@s-opensource.com> 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 There are lots of ioctls mentioned there that aren't cross-referenced. Convert the const to cross references. That makes it visually better, and improves navigation along the document. Signed-off-by: Mauro Carvalho Chehab --- Documentation/linux_tv/media/v4l/dmabuf.rst | 41 ++++++++++++++++------------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/Documentation/linux_tv/media/v4l/dmabuf.rst b/Documentation/linux_tv/media/v4l/dmabuf.rst index 86cdc255e447..0b2113778cc9 100644 --- a/Documentation/linux_tv/media/v4l/dmabuf.rst +++ b/Documentation/linux_tv/media/v4l/dmabuf.rst @@ -20,9 +20,9 @@ exporting V4L2 buffers as DMABUF file descriptors. Input and output devices support the streaming I/O method when the ``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct :ref:`v4l2_capability ` returned by the -:ref:`VIDIOC_QUERYCAP` ioctl is set. Whether +:ref:`VIDIOC_QUERYCAP ` ioctl is set. Whether importing DMA buffers through DMABUF file descriptors is supported is -determined by calling the :ref:`VIDIOC_REQBUFS` +determined by calling the :ref:`VIDIOC_REQBUFS ` ioctl with the memory type set to ``V4L2_MEMORY_DMABUF``. This I/O method is dedicated to sharing DMA buffers between different @@ -34,7 +34,7 @@ such file descriptor are exchanged. The descriptors and meta-information are passed in struct :ref:`v4l2_buffer ` (or in struct :ref:`v4l2_plane ` in the multi-planar API case). The driver must be switched into DMABUF I/O mode by calling the -:ref:`VIDIOC_REQBUFS` with the desired buffer type. +:ref:`VIDIOC_REQBUFS ` with the desired buffer type. .. code-block:: c @@ -57,10 +57,10 @@ driver must be switched into DMABUF I/O mode by calling the } The buffer (plane) file descriptor is passed on the fly with the -:ref:`VIDIOC_QBUF` ioctl. In case of multiplanar +:ref:`VIDIOC_QBUF ` ioctl. In case of multiplanar buffers, every plane can be associated with a different DMABUF descriptor. Although buffers are commonly cycled, applications can pass -a different DMABUF descriptor at each ``VIDIOC_QBUF`` call. +a different DMABUF descriptor at each :ref:`VIDIOC_QBUF ` call. .. code-block:: c @@ -119,7 +119,7 @@ Captured or displayed buffers are dequeued with the buffer at any time between the completion of the DMA and this ioctl. The memory is also unlocked when :ref:`VIDIOC_STREAMOFF ` is called, -:ref:`VIDIOC_REQBUFS`, or when the device is closed. +:ref:`VIDIOC_REQBUFS `, or when the device is closed. For capturing applications it is customary to enqueue a number of empty buffers, to start capturing and enter the read loop. Here the @@ -129,24 +129,27 @@ and enqueue buffers, when enough buffers are stacked up output is started. In the write loop, when the application runs out of free buffers it must wait until an empty buffer can be dequeued and reused. Two methods exist to suspend execution of the application until one or -more buffers can be dequeued. By default ``VIDIOC_DQBUF`` blocks when no -buffer is in the outgoing queue. When the ``O_NONBLOCK`` flag was given -to the :ref:`open() ` function, ``VIDIOC_DQBUF`` returns -immediately with an ``EAGAIN`` error code when no buffer is available. The +more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF +` blocks when no buffer is in the outgoing queue. When the +``O_NONBLOCK`` flag was given to the :ref:`open() ` function, +:ref:`VIDIOC_DQBUF ` returns immediately with an ``EAGAIN`` +error code when no buffer is available. The :ref:`select() ` and :ref:`poll() ` functions are always available. To start and stop capturing or displaying applications call the -:ref:`VIDIOC_STREAMON` and +:ref:`VIDIOC_STREAMON ` and :ref:`VIDIOC_STREAMOFF ` ioctls. Note that -``VIDIOC_STREAMOFF`` removes all buffers from both queues and unlocks -all buffers as a side effect. Since there is no notion of doing anything -"now" on a multitasking system, if an application needs to synchronize -with another event it should examine the struct -:ref:`v4l2_buffer ` ``timestamp`` of captured or +:ref:`VIDIOC_STREAMOFF ` removes all buffers from +both queues and unlocks all buffers as a side effect. Since there is no +notion of doing anything "now" on a multitasking system, if an +application needs to synchronize with another event it should examine +the struct :ref:`v4l2_buffer ` ``timestamp`` of captured or outputted buffers. Drivers implementing DMABUF importing I/O must support the -``VIDIOC_REQBUFS``, ``VIDIOC_QBUF``, ``VIDIOC_DQBUF``, -``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctls, and the -:ref:`select() ` and :ref:`poll() ` functions. +:ref:`VIDIOC_REQBUFS `, :ref:`VIDIOC_QBUF `, +:ref:`VIDIOC_DQBUF `, :ref:`VIDIOC_STREAMON +` and :ref:`VIDIOC_STREAMOFF ` ioctls, +and the :ref:`select() ` and :ref:`poll() ` +functions.