From patchwork Tue Jul 5 01:31:02 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: 9213427 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 3BDC960467 for ; Tue, 5 Jul 2016 01:32:50 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 2A9E028800 for ; Tue, 5 Jul 2016 01:32:50 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 1F75228802; Tue, 5 Jul 2016 01:32:50 +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 95F2728800 for ; Tue, 5 Jul 2016 01:32:49 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932984AbcGEBcb (ORCPT ); Mon, 4 Jul 2016 21:32:31 -0400 Received: from bombadil.infradead.org ([198.137.202.9]:38630 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753851AbcGEBb0 (ORCPT ); Mon, 4 Jul 2016 21:31:26 -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-0001gb-B4; 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-0001ba-G3; 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 27/41] Documentation: userp.rst: Add ioctl cross references Date: Mon, 4 Jul 2016 22:31:02 -0300 Message-Id: <56510b63d7769bf7cbda2a80c446f1820c69223c.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. While here, remove bad whitespaces. Signed-off-by: Mauro Carvalho Chehab --- Documentation/linux_tv/media/v4l/userp.rst | 56 ++++++++++++++++-------------- 1 file changed, 29 insertions(+), 27 deletions(-) diff --git a/Documentation/linux_tv/media/v4l/userp.rst b/Documentation/linux_tv/media/v4l/userp.rst index 6db760d3d725..188c0b9f169e 100644 --- a/Documentation/linux_tv/media/v4l/userp.rst +++ b/Documentation/linux_tv/media/v4l/userp.rst @@ -24,7 +24,7 @@ driver must be switched into user pointer I/O mode by calling the :ref:`VIDIOC_REQBUFS` with the desired buffer type. No buffers (planes) are allocated beforehand, consequently they are not indexed and cannot be queried like mapped buffers with the -``VIDIOC_QUERYBUF`` ioctl. +:ref:`VIDIOC_QUERYBUF ` ioctl. .. code-block:: c @@ -37,23 +37,23 @@ indexed and cannot be queried like mapped buffers with the reqbuf.memory = V4L2_MEMORY_USERPTR; if (ioctl (fd, VIDIOC_REQBUFS, &reqbuf) == -1) { - if (errno == EINVAL) - printf ("Video capturing or user pointer streaming is not supported\\n"); - else - perror ("VIDIOC_REQBUFS"); + if (errno == EINVAL) + printf ("Video capturing or user pointer streaming is not supported\\n"); + else + perror ("VIDIOC_REQBUFS"); - exit (EXIT_FAILURE); + exit (EXIT_FAILURE); } Buffer (plane) addresses and sizes are passed on the fly with the -:ref:`VIDIOC_QBUF` ioctl. Although buffers are commonly +:ref:`VIDIOC_QBUF ` ioctl. Although buffers are commonly cycled, applications can pass different addresses and sizes at each -``VIDIOC_QBUF`` call. If required by the hardware the driver swaps -memory pages within physical memory to create a continuous area of -memory. This happens transparently to the application in the virtual -memory subsystem of the kernel. When buffer pages have been swapped out -to disk they are brought back and finally locked in physical memory for -DMA. [1]_ +:ref:`VIDIOC_QBUF ` call. If required by the hardware the +driver swaps memory pages within physical memory to create a continuous +area of memory. This happens transparently to the application in the +virtual memory subsystem of the kernel. When buffer pages have been +swapped out to disk they are brought back and finally locked in physical +memory for DMA. [1]_ Filled or displayed buffers are dequeued with the :ref:`VIDIOC_DQBUF ` ioctl. The driver can unlock the @@ -75,26 +75,28 @@ 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 -:ref:`select() ` or :ref:`poll() ` function -are always available. +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() +` or :ref:`poll() ` function are always +available. To start and stop capturing or output applications call the -:ref:`VIDIOC_STREAMON` and +:ref:`VIDIOC_STREAMON ` and :ref:`VIDIOC_STREAMOFF ` ioctl. Note -``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 user pointer I/O must support the -``VIDIOC_REQBUFS``, ``VIDIOC_QBUF``, ``VIDIOC_DQBUF``, -``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl, the +:ref:`VIDIOC_REQBUFS `, :ref:`VIDIOC_QBUF `, +:ref:`VIDIOC_DQBUF `, :ref:`VIDIOC_STREAMON ` +and :ref:`VIDIOC_STREAMOFF ` ioctls, the :ref:`select() ` and :ref:`poll() ` function. [2]_ .. [1]