From 60c2820d0f6d3497975b6488e2599f8f611d8b95 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 8 Jul 2016 11:40:06 -0300 Subject: doc_rst: rename the media Sphinx suff to Documentation/media The name of the subsystem is "media", and not "linux_tv". Also, as we plan to add other stuff there in the future, let's rename also the media uAPI book to media_uapi, to make it clearer. No functional changes. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/vidioc-reqbufs.rst | 125 ++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 Documentation/media/uapi/v4l/vidioc-reqbufs.rst (limited to 'Documentation/media/uapi/v4l/vidioc-reqbufs.rst') diff --git a/Documentation/media/uapi/v4l/vidioc-reqbufs.rst b/Documentation/media/uapi/v4l/vidioc-reqbufs.rst new file mode 100644 index 000000000000..c25b0719c2ff --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-reqbufs.rst @@ -0,0 +1,125 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_REQBUFS: + +******************** +ioctl VIDIOC_REQBUFS +******************** + +Name +==== + +VIDIOC_REQBUFS - Initiate Memory Mapping or User Pointer I/O + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_requestbuffers *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + VIDIOC_REQBUFS + +``argp`` + + +Description +=========== + +This ioctl is used to initiate :ref:`memory mapped `, +:ref:`user pointer ` or :ref:`DMABUF ` based I/O. +Memory mapped buffers are located in device memory and must be allocated +with this ioctl before they can be mapped into the application's address +space. User buffers are allocated by applications themselves, and this +ioctl is merely used to switch the driver into user pointer I/O mode and +to setup some internal structures. Similarly, DMABUF buffers are +allocated by applications through a device driver, and this ioctl only +configures the driver into DMABUF I/O mode without performing any direct +allocation. + +To allocate device buffers applications initialize all fields of the +:ref:`struct v4l2_requestbuffers ` structure. They set the ``type`` +field to the respective stream or buffer type, the ``count`` field to +the desired number of buffers, ``memory`` must be set to the requested +I/O method and the ``reserved`` array must be zeroed. When the ioctl is +called with a pointer to this structure the driver will attempt to +allocate the requested number of buffers and it stores the actual number +allocated in the ``count`` field. It can be smaller than the number +requested, even zero, when the driver runs out of free memory. A larger +number is also possible when the driver requires more buffers to +function correctly. For example video output requires at least two +buffers, one displayed and one filled by the application. + +When the I/O method is not supported the ioctl returns an ``EINVAL`` error +code. + +Applications can call :ref:`VIDIOC_REQBUFS` again to change the number of +buffers, however this cannot succeed when any buffers are still mapped. +A ``count`` value of zero frees all buffers, after aborting or finishing +any DMA in progress, an implicit +:ref:`VIDIOC_STREAMOFF `. + + +.. _v4l2-requestbuffers: + +.. flat-table:: struct v4l2_requestbuffers + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``count`` + + - The number of buffers requested or granted. + + - .. row 2 + + - __u32 + + - ``type`` + + - Type of the stream or buffers, this is the same as the struct + :ref:`v4l2_format ` ``type`` field. See + :ref:`v4l2-buf-type` for valid values. + + - .. row 3 + + - __u32 + + - ``memory`` + + - Applications set this field to ``V4L2_MEMORY_MMAP``, + ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See + :ref:`v4l2-memory`. + + - .. row 4 + + - __u32 + + - ``reserved``\ [2] + + - A place holder for future extensions. Drivers and applications + must set the array to zero. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +EINVAL + The buffer type (``type`` field) or the requested I/O method + (``memory``) is not supported. -- cgit v1.2.1