Commit cbb6a7f5 authored by Alexandre Courbot's avatar Alexandre Courbot Committed by Mauro Carvalho Chehab
Browse files

media: Documentation: v4l: document request API 



Document the request API for V4L2 devices, and amend the documentation
of system calls influenced by it.

Signed-off-by: default avatarAlexandre Courbot <acourbot@chromium.org>
Signed-off-by: default avatarHans Verkuil <hans.verkuil@cisco.com>
Reviewed-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
parent d842a7cf

Documentation/media/uapi/mediactl/media-controller.rst

+1 −0
Original line number Diff line number Diff line
@@ -21,6 +21,7 @@ Part IV - Media Controller API 
    media-controller-intro

    media-controller-model

    media-types

    request-api

    media-funcs

    media-header

Documentation/media/uapi/mediactl/media-funcs.rst

+6 −0
Original line number Diff line number Diff line
@@ -16,3 +16,9 @@ Function Reference 
    media-ioc-enum-entities

    media-ioc-enum-links

    media-ioc-setup-link

    media-ioc-request-alloc

    request-func-close

    request-func-ioctl

    request-func-poll

    media-request-ioc-queue

    media-request-ioc-reinit

Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst

0 → 100644
+65 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections



.. _media_ioc_request_alloc:



*****************************

ioctl MEDIA_IOC_REQUEST_ALLOC

*****************************



Name

====



MEDIA_IOC_REQUEST_ALLOC - Allocate a request





Synopsis

========



.. c:function:: int ioctl( int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp )

    :name: MEDIA_IOC_REQUEST_ALLOC





Arguments

=========



``fd``

    File descriptor returned by :ref:`open() <media-func-open>`.



``argp``

    Pointer to an integer.





Description

===========



If the media device supports :ref:`requests <media-request-api>`, then

this ioctl can be used to allocate a request. If it is not supported, then

``errno`` is set to ``ENOTTY``. A request is accessed through a file descriptor

that is returned in ``*argp``.



If the request was successfully allocated, then the request file descriptor

can be passed to the :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,

:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,

:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and

:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctls.



In addition, the request can be queued by calling

:ref:`MEDIA_REQUEST_IOC_QUEUE` and re-initialized by calling

:ref:`MEDIA_REQUEST_IOC_REINIT`.



Finally, the file descriptor can be :ref:`polled <request-func-poll>` to wait

for the request to complete.



The request will remain allocated until all the file descriptors associated

with it are closed by :ref:`close() <request-func-close>` and the driver no

longer uses the request internally.



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 <gen-errors>` chapter.



ENOTTY

    The driver has no support for requests.

Documentation/media/uapi/mediactl/media-request-ioc-queue.rst

0 → 100644
+82 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections



.. _media_request_ioc_queue:



*****************************

ioctl MEDIA_REQUEST_IOC_QUEUE

*****************************



Name

====



MEDIA_REQUEST_IOC_QUEUE - Queue a request





Synopsis

========



.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_QUEUE )

    :name: MEDIA_REQUEST_IOC_QUEUE





Arguments

=========



``request_fd``

    File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.





Description

===========



If the media device supports :ref:`requests <media-request-api>`, then

this request ioctl can be used to queue a previously allocated request.



If the request was successfully queued, then the file descriptor can be

:ref:`polled <request-func-poll>` to wait for the request to complete.



If the request was already queued before, then ``EBUSY`` is returned.

Other errors can be returned if the contents of the request contained

invalid or inconsistent data, see the next section for a list of

common error codes. On error both the request and driver state are unchanged.



Typically if you get an error here, then that means that the application

did something wrong and you have to fix the application.



Once a request is queued, then the driver is required to gracefully handle

errors that occur when the request is applied to the hardware. The

exception is the ``EIO`` error which signals a fatal error that requires

the application to stop streaming to reset the hardware state.



It is not allowed to mix queuing requests with queuing buffers directly

(without a request). ``EPERM`` will be returned if the first buffer was

queued directly and you next try to queue a request, or vice versa.



A request must contain at least one buffer, otherwise this ioctl will

return an ``ENOENT`` error.



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 <gen-errors>` chapter.



EBUSY

    The request was already queued.

EPERM

    The application queued the first buffer directly, but later attempted

    to use a request. It is not permitted to mix the two APIs.

ENOENT

    The request did not contain any buffers. All requests are required

    to have at least one buffer. This can also be returned if required

    controls are missing.

ENOMEM

    Out of memory when allocating internal data structures for this

    request.

EINVAL

    The request has invalid data.

EIO

    The hardware is in a bad state. To recover, the application needs to

    stop streaming to reset the hardware state and then try to restart

    streaming.

Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst

0 → 100644
+51 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections



.. _media_request_ioc_reinit:



******************************

ioctl MEDIA_REQUEST_IOC_REINIT

******************************



Name

====



MEDIA_REQUEST_IOC_REINIT - Re-initialize a request





Synopsis

========



.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_REINIT )

    :name: MEDIA_REQUEST_IOC_REINIT





Arguments

=========



``request_fd``

    File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.



Description

===========



If the media device supports :ref:`requests <media-request-api>`, then

this request ioctl can be used to re-initialize a previously allocated

request.



Re-initializing a request will clear any existing data from the request.

This avoids having to :ref:`close() <request-func-close>` a completed

request and allocate a new request. Instead the completed request can just

be re-initialized and it is ready to be used again.



A request can only be re-initialized if it either has not been queued

yet, or if it was queued and completed. Otherwise it will set ``errno``

to ``EBUSY``. No other error codes can be returned.



Return Value

============



On success 0 is returned, on error -1 and the ``errno`` variable is set

appropriately.



EBUSY

    The request is queued but not yet completed.