Re: [PATCHv15 29/35] Documentation: v4l: document request API
On 03/07/18 16:08, Mauro Carvalho Chehab wrote: > Em Tue, 3 Jul 2018 15:02:05 +0200 > Hans Verkuil escreveu: > >> On 03/07/18 13:50, Mauro Carvalho Chehab wrote: >>> Em Mon, 4 Jun 2018 13:46:42 +0200 >>> Hans Verkuil escreveu: >>> From: Alexandre Courbot Document the request API for V4L2 devices, and amend the documentation of system calls influenced by it. >>> >>> I'm starting reviewing the patch series from this patch, as it defines >>> how the request API is supposed to work. Some of my comments below may >>> reflect on code changes, in order for the core (and drivers) to be >>> compliant with the uAPI specified here. >>> >>> So, I prefer to discuss first the contents of this patch, before start >>> reviewing the remaining patches. >>> Signed-off-by: Alexandre Courbot Signed-off-by: Hans Verkuil --- .../media/uapi/mediactl/media-controller.rst | 1 + .../media/uapi/mediactl/media-funcs.rst | 3 + .../uapi/mediactl/media-ioc-request-alloc.rst | 71 ++ .../uapi/mediactl/media-request-ioc-queue.rst | 50 .../mediactl/media-request-ioc-reinit.rst | 51 .../media/uapi/mediactl/request-api.rst | 219 ++ Documentation/media/uapi/v4l/buffer.rst | 18 +- .../media/uapi/v4l/vidioc-g-ext-ctrls.rst | 28 ++- Documentation/media/uapi/v4l/vidioc-qbuf.rst | 11 + .../media/videodev2.h.rst.exceptions | 1 + 10 files changed, 447 insertions(+), 6 deletions(-) create mode 100644 Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst create mode 100644 Documentation/media/uapi/mediactl/media-request-ioc-queue.rst create mode 100644 Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst create mode 100644 Documentation/media/uapi/mediactl/request-api.rst diff --git a/Documentation/media/uapi/mediactl/media-controller.rst b/Documentation/media/uapi/mediactl/media-controller.rst index 0eea4f9a07d5..66aff38cd499 100644 --- a/Documentation/media/uapi/mediactl/media-controller.rst +++ b/Documentation/media/uapi/mediactl/media-controller.rst @@ -21,6 +21,7 @@ Part IV - Media Controller API media-controller-intro media-controller-model media-types +request-api media-funcs media-header diff --git a/Documentation/media/uapi/mediactl/media-funcs.rst b/Documentation/media/uapi/mediactl/media-funcs.rst index 076856501cdb..f4da9b3e17ec 100644 --- a/Documentation/media/uapi/mediactl/media-funcs.rst +++ b/Documentation/media/uapi/mediactl/media-funcs.rst @@ -16,3 +16,6 @@ Function Reference media-ioc-enum-entities media-ioc-enum-links media-ioc-setup-link +media-ioc-request-alloc +media-request-ioc-queue +media-request-ioc-reinit diff --git a/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst b/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst new file mode 100644 index ..d45a94c9e23c --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst @@ -0,0 +1,71 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +.. _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, struct media_request_alloc *argp ) +:name: MEDIA_IOC_REQUEST_ALLOC + + +Arguments += + +``fd`` +File descriptor returned by :ref:`open() `. + +``argp`` + + +Description +=== + +If the media device supports :ref:`requests `, then +this ioctl can be used to allocate a request. >>> >>> Perhaps we should mention that otherwise it would set errno to ENOTTY. >> >> Will add. >> >>> A request is accessed through +a file descriptor that is returned in struct :c:type:`media_request_alloc`. + +If the request was successfully allocated, then the request file descriptor +can be passed to :ref:`ioctl VIDIOC_QBUF `, +:ref:`ioctl VIDIOC_G_EXT_CTRLS `, +:ref:`ioctl VIDIOC_S_EXT_CTRLS ` and +:ref:`ioctl VIDIOC_TRY_EXT_CTRLS `. + +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 polled to wait for the request to +complete. + +To free the request the file descriptor has to be closed. >>> >>> Hmm... I don't think this is clear
Re: [PATCHv15 29/35] Documentation: v4l: document request API
Em Tue, 3 Jul 2018 15:02:05 +0200 Hans Verkuil escreveu: > On 03/07/18 13:50, Mauro Carvalho Chehab wrote: > > Em Mon, 4 Jun 2018 13:46:42 +0200 > > Hans Verkuil escreveu: > > > >> From: Alexandre Courbot > >> > >> Document the request API for V4L2 devices, and amend the documentation > >> of system calls influenced by it. > > > > I'm starting reviewing the patch series from this patch, as it defines > > how the request API is supposed to work. Some of my comments below may > > reflect on code changes, in order for the core (and drivers) to be > > compliant with the uAPI specified here. > > > > So, I prefer to discuss first the contents of this patch, before start > > reviewing the remaining patches. > > > >> > >> Signed-off-by: Alexandre Courbot > >> Signed-off-by: Hans Verkuil > >> --- > >> .../media/uapi/mediactl/media-controller.rst | 1 + > >> .../media/uapi/mediactl/media-funcs.rst | 3 + > >> .../uapi/mediactl/media-ioc-request-alloc.rst | 71 ++ > >> .../uapi/mediactl/media-request-ioc-queue.rst | 50 > >> .../mediactl/media-request-ioc-reinit.rst | 51 > >> .../media/uapi/mediactl/request-api.rst | 219 ++ > >> Documentation/media/uapi/v4l/buffer.rst | 18 +- > >> .../media/uapi/v4l/vidioc-g-ext-ctrls.rst | 28 ++- > >> Documentation/media/uapi/v4l/vidioc-qbuf.rst | 11 + > >> .../media/videodev2.h.rst.exceptions | 1 + > >> 10 files changed, 447 insertions(+), 6 deletions(-) > >> create mode 100644 > >> Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst > >> create mode 100644 > >> Documentation/media/uapi/mediactl/media-request-ioc-queue.rst > >> create mode 100644 > >> Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst > >> create mode 100644 Documentation/media/uapi/mediactl/request-api.rst > >> > >> diff --git a/Documentation/media/uapi/mediactl/media-controller.rst > >> b/Documentation/media/uapi/mediactl/media-controller.rst > >> index 0eea4f9a07d5..66aff38cd499 100644 > >> --- a/Documentation/media/uapi/mediactl/media-controller.rst > >> +++ b/Documentation/media/uapi/mediactl/media-controller.rst > >> @@ -21,6 +21,7 @@ Part IV - Media Controller API > >> media-controller-intro > >> media-controller-model > >> media-types > >> +request-api > >> media-funcs > >> media-header > >> > >> diff --git a/Documentation/media/uapi/mediactl/media-funcs.rst > >> b/Documentation/media/uapi/mediactl/media-funcs.rst > >> index 076856501cdb..f4da9b3e17ec 100644 > >> --- a/Documentation/media/uapi/mediactl/media-funcs.rst > >> +++ b/Documentation/media/uapi/mediactl/media-funcs.rst > >> @@ -16,3 +16,6 @@ Function Reference > >> media-ioc-enum-entities > >> media-ioc-enum-links > >> media-ioc-setup-link > >> +media-ioc-request-alloc > >> +media-request-ioc-queue > >> +media-request-ioc-reinit > >> diff --git a/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst > >> b/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst > >> new file mode 100644 > >> index ..d45a94c9e23c > >> --- /dev/null > >> +++ b/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst > >> @@ -0,0 +1,71 @@ > >> +.. SPDX-License-Identifier: GPL-2.0-only > >> + > >> +.. _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, struct > >> media_request_alloc *argp ) > >> +:name: MEDIA_IOC_REQUEST_ALLOC > >> + > >> + > >> +Arguments > >> += > >> + > >> +``fd`` > >> +File descriptor returned by :ref:`open() `. > >> + > >> +``argp`` > >> + > >> + > >> +Description > >> +=== > >> + > >> +If the media device supports :ref:`requests `, then > >> +this ioctl can be used to allocate a request. > > > > Perhaps we should mention that otherwise it would set errno to ENOTTY. > > Will add. > > > > >> A request is accessed through > >> +a file descriptor that is returned in struct > >> :c:type:`media_request_alloc`. > >> + > >> +If the request was successfully allocated, then the request file > >> descriptor > >> +can be passed to :ref:`ioctl VIDIOC_QBUF `, > >> +:ref:`ioctl VIDIOC_G_EXT_CTRLS `, > >> +:ref:`ioctl VIDIOC_S_EXT_CTRLS ` and > >> +:ref:`ioctl VIDIOC_TRY_EXT_CTRLS `. > >> + > >> +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 polled to wait for the request to > >> +complete. > >> + > >> +To free the request the file descriptor has to be closed. > > > > Hmm... I don't think this is clear enough. After reading this paragraph, > > I came back
Re: [PATCHv15 29/35] Documentation: v4l: document request API
On 03/07/18 13:50, Mauro Carvalho Chehab wrote: > Em Mon, 4 Jun 2018 13:46:42 +0200 > Hans Verkuil escreveu: > >> From: Alexandre Courbot >> >> Document the request API for V4L2 devices, and amend the documentation >> of system calls influenced by it. > > I'm starting reviewing the patch series from this patch, as it defines > how the request API is supposed to work. Some of my comments below may > reflect on code changes, in order for the core (and drivers) to be > compliant with the uAPI specified here. > > So, I prefer to discuss first the contents of this patch, before start > reviewing the remaining patches. > >> >> Signed-off-by: Alexandre Courbot >> Signed-off-by: Hans Verkuil >> --- >> .../media/uapi/mediactl/media-controller.rst | 1 + >> .../media/uapi/mediactl/media-funcs.rst | 3 + >> .../uapi/mediactl/media-ioc-request-alloc.rst | 71 ++ >> .../uapi/mediactl/media-request-ioc-queue.rst | 50 >> .../mediactl/media-request-ioc-reinit.rst | 51 >> .../media/uapi/mediactl/request-api.rst | 219 ++ >> Documentation/media/uapi/v4l/buffer.rst | 18 +- >> .../media/uapi/v4l/vidioc-g-ext-ctrls.rst | 28 ++- >> Documentation/media/uapi/v4l/vidioc-qbuf.rst | 11 + >> .../media/videodev2.h.rst.exceptions | 1 + >> 10 files changed, 447 insertions(+), 6 deletions(-) >> create mode 100644 >> Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst >> create mode 100644 >> Documentation/media/uapi/mediactl/media-request-ioc-queue.rst >> create mode 100644 >> Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst >> create mode 100644 Documentation/media/uapi/mediactl/request-api.rst >> >> diff --git a/Documentation/media/uapi/mediactl/media-controller.rst >> b/Documentation/media/uapi/mediactl/media-controller.rst >> index 0eea4f9a07d5..66aff38cd499 100644 >> --- a/Documentation/media/uapi/mediactl/media-controller.rst >> +++ b/Documentation/media/uapi/mediactl/media-controller.rst >> @@ -21,6 +21,7 @@ Part IV - Media Controller API >> media-controller-intro >> media-controller-model >> media-types >> +request-api >> media-funcs >> media-header >> >> diff --git a/Documentation/media/uapi/mediactl/media-funcs.rst >> b/Documentation/media/uapi/mediactl/media-funcs.rst >> index 076856501cdb..f4da9b3e17ec 100644 >> --- a/Documentation/media/uapi/mediactl/media-funcs.rst >> +++ b/Documentation/media/uapi/mediactl/media-funcs.rst >> @@ -16,3 +16,6 @@ Function Reference >> media-ioc-enum-entities >> media-ioc-enum-links >> media-ioc-setup-link >> +media-ioc-request-alloc >> +media-request-ioc-queue >> +media-request-ioc-reinit >> diff --git a/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst >> b/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst >> new file mode 100644 >> index ..d45a94c9e23c >> --- /dev/null >> +++ b/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst >> @@ -0,0 +1,71 @@ >> +.. SPDX-License-Identifier: GPL-2.0-only >> + >> +.. _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, struct >> media_request_alloc *argp ) >> +:name: MEDIA_IOC_REQUEST_ALLOC >> + >> + >> +Arguments >> += >> + >> +``fd`` >> +File descriptor returned by :ref:`open() `. >> + >> +``argp`` >> + >> + >> +Description >> +=== >> + >> +If the media device supports :ref:`requests `, then >> +this ioctl can be used to allocate a request. > > Perhaps we should mention that otherwise it would set errno to ENOTTY. Will add. > >> A request is accessed through >> +a file descriptor that is returned in struct :c:type:`media_request_alloc`. >> + >> +If the request was successfully allocated, then the request file descriptor >> +can be passed to :ref:`ioctl VIDIOC_QBUF `, >> +:ref:`ioctl VIDIOC_G_EXT_CTRLS `, >> +:ref:`ioctl VIDIOC_S_EXT_CTRLS ` and >> +:ref:`ioctl VIDIOC_TRY_EXT_CTRLS `. >> + >> +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 polled to wait for the request to >> +complete. >> + >> +To free the request the file descriptor has to be closed. > > Hmm... I don't think this is clear enough. After reading this paragraph, > I came back to patch 1, in order to see what's the ioctl to be called > to free the request, only to notice that there's none. > > So, I guess what you wanted to say, instead, is that: > > "A request will remain allocated until the associated file descriptor is > closed by ::c:func:`close() ` and after the Kernel stops > using the request." That's a lot
Re: [PATCHv15 29/35] Documentation: v4l: document request API
Em Mon, 4 Jun 2018 13:46:42 +0200
Hans Verkuil escreveu:
> From: Alexandre Courbot
>
> Document the request API for V4L2 devices, and amend the documentation
> of system calls influenced by it.
I'm starting reviewing the patch series from this patch, as it defines
how the request API is supposed to work. Some of my comments below may
reflect on code changes, in order for the core (and drivers) to be
compliant with the uAPI specified here.
So, I prefer to discuss first the contents of this patch, before start
reviewing the remaining patches.
>
> Signed-off-by: Alexandre Courbot
> Signed-off-by: Hans Verkuil
> ---
> .../media/uapi/mediactl/media-controller.rst | 1 +
> .../media/uapi/mediactl/media-funcs.rst | 3 +
> .../uapi/mediactl/media-ioc-request-alloc.rst | 71 ++
> .../uapi/mediactl/media-request-ioc-queue.rst | 50
> .../mediactl/media-request-ioc-reinit.rst | 51
> .../media/uapi/mediactl/request-api.rst | 219 ++
> Documentation/media/uapi/v4l/buffer.rst | 18 +-
> .../media/uapi/v4l/vidioc-g-ext-ctrls.rst | 28 ++-
> Documentation/media/uapi/v4l/vidioc-qbuf.rst | 11 +
> .../media/videodev2.h.rst.exceptions | 1 +
> 10 files changed, 447 insertions(+), 6 deletions(-)
> create mode 100644
> Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst
> create mode 100644
> Documentation/media/uapi/mediactl/media-request-ioc-queue.rst
> create mode 100644
> Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst
> create mode 100644 Documentation/media/uapi/mediactl/request-api.rst
>
> diff --git a/Documentation/media/uapi/mediactl/media-controller.rst
> b/Documentation/media/uapi/mediactl/media-controller.rst
> index 0eea4f9a07d5..66aff38cd499 100644
> --- a/Documentation/media/uapi/mediactl/media-controller.rst
> +++ b/Documentation/media/uapi/mediactl/media-controller.rst
> @@ -21,6 +21,7 @@ Part IV - Media Controller API
> media-controller-intro
> media-controller-model
> media-types
> +request-api
> media-funcs
> media-header
>
> diff --git a/Documentation/media/uapi/mediactl/media-funcs.rst
> b/Documentation/media/uapi/mediactl/media-funcs.rst
> index 076856501cdb..f4da9b3e17ec 100644
> --- a/Documentation/media/uapi/mediactl/media-funcs.rst
> +++ b/Documentation/media/uapi/mediactl/media-funcs.rst
> @@ -16,3 +16,6 @@ Function Reference
> media-ioc-enum-entities
> media-ioc-enum-links
> media-ioc-setup-link
> +media-ioc-request-alloc
> +media-request-ioc-queue
> +media-request-ioc-reinit
> diff --git a/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst
> b/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst
> new file mode 100644
> index ..d45a94c9e23c
> --- /dev/null
> +++ b/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst
> @@ -0,0 +1,71 @@
> +.. SPDX-License-Identifier: GPL-2.0-only
> +
> +.. _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, struct
> media_request_alloc *argp )
> +:name: MEDIA_IOC_REQUEST_ALLOC
> +
> +
> +Arguments
> +=
> +
> +``fd``
> +File descriptor returned by :ref:`open() `.
> +
> +``argp``
> +
> +
> +Description
> +===
> +
> +If the media device supports :ref:`requests `, then
> +this ioctl can be used to allocate a request.
Perhaps we should mention that otherwise it would set errno to ENOTTY.
> A request is accessed through
> +a file descriptor that is returned in struct :c:type:`media_request_alloc`.
> +
> +If the request was successfully allocated, then the request file descriptor
> +can be passed to :ref:`ioctl VIDIOC_QBUF `,
> +:ref:`ioctl VIDIOC_G_EXT_CTRLS `,
> +:ref:`ioctl VIDIOC_S_EXT_CTRLS ` and
> +:ref:`ioctl VIDIOC_TRY_EXT_CTRLS `.
> +
> +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 polled to wait for the request to
> +complete.
> +
> +To free the request the file descriptor has to be closed.
Hmm... I don't think this is clear enough. After reading this paragraph,
I came back to patch 1, in order to see what's the ioctl to be called
to free the request, only to notice that there's none.
So, I guess what you wanted to say, instead, is that:
"A request will remain allocated until the associated file descriptor is
closed by ::c:func:`close() ` and after the Kernel stops
using the request."
(see below for a discussion about the close() reference)
> +
> +.. c:type:: media_request_alloc
> +
> +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
> +
> +.. flat-table:: struct media_request_alloc
> +:header-rows: 0
> +
[PATCHv15 29/35] Documentation: v4l: document request API
From: Alexandre Courbot
Document the request API for V4L2 devices, and amend the documentation
of system calls influenced by it.
Signed-off-by: Alexandre Courbot
Signed-off-by: Hans Verkuil
---
.../media/uapi/mediactl/media-controller.rst | 1 +
.../media/uapi/mediactl/media-funcs.rst | 3 +
.../uapi/mediactl/media-ioc-request-alloc.rst | 71 ++
.../uapi/mediactl/media-request-ioc-queue.rst | 50
.../mediactl/media-request-ioc-reinit.rst | 51
.../media/uapi/mediactl/request-api.rst | 219 ++
Documentation/media/uapi/v4l/buffer.rst | 18 +-
.../media/uapi/v4l/vidioc-g-ext-ctrls.rst | 28 ++-
Documentation/media/uapi/v4l/vidioc-qbuf.rst | 11 +
.../media/videodev2.h.rst.exceptions | 1 +
10 files changed, 447 insertions(+), 6 deletions(-)
create mode 100644
Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst
create mode 100644
Documentation/media/uapi/mediactl/media-request-ioc-queue.rst
create mode 100644
Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst
create mode 100644 Documentation/media/uapi/mediactl/request-api.rst
diff --git a/Documentation/media/uapi/mediactl/media-controller.rst
b/Documentation/media/uapi/mediactl/media-controller.rst
index 0eea4f9a07d5..66aff38cd499 100644
--- a/Documentation/media/uapi/mediactl/media-controller.rst
+++ b/Documentation/media/uapi/mediactl/media-controller.rst
@@ -21,6 +21,7 @@ Part IV - Media Controller API
media-controller-intro
media-controller-model
media-types
+request-api
media-funcs
media-header
diff --git a/Documentation/media/uapi/mediactl/media-funcs.rst
b/Documentation/media/uapi/mediactl/media-funcs.rst
index 076856501cdb..f4da9b3e17ec 100644
--- a/Documentation/media/uapi/mediactl/media-funcs.rst
+++ b/Documentation/media/uapi/mediactl/media-funcs.rst
@@ -16,3 +16,6 @@ Function Reference
media-ioc-enum-entities
media-ioc-enum-links
media-ioc-setup-link
+media-ioc-request-alloc
+media-request-ioc-queue
+media-request-ioc-reinit
diff --git a/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst
b/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst
new file mode 100644
index ..d45a94c9e23c
--- /dev/null
+++ b/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst
@@ -0,0 +1,71 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+.. _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, struct
media_request_alloc *argp )
+:name: MEDIA_IOC_REQUEST_ALLOC
+
+
+Arguments
+=
+
+``fd``
+File descriptor returned by :ref:`open() `.
+
+``argp``
+
+
+Description
+===
+
+If the media device supports :ref:`requests `, then
+this ioctl can be used to allocate a request. A request is accessed through
+a file descriptor that is returned in struct :c:type:`media_request_alloc`.
+
+If the request was successfully allocated, then the request file descriptor
+can be passed to :ref:`ioctl VIDIOC_QBUF `,
+:ref:`ioctl VIDIOC_G_EXT_CTRLS `,
+:ref:`ioctl VIDIOC_S_EXT_CTRLS ` and
+:ref:`ioctl VIDIOC_TRY_EXT_CTRLS `.
+
+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 polled to wait for the request to
+complete.
+
+To free the request the file descriptor has to be closed.
+
+.. c:type:: media_request_alloc
+
+.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
+
+.. flat-table:: struct media_request_alloc
+:header-rows: 0
+:stub-columns: 0
+:widths: 1 1 2
+
+* - __s32
+ - ``fd``
+ - The file descriptor of the request.
+
+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.
diff --git a/Documentation/media/uapi/mediactl/media-request-ioc-queue.rst
b/Documentation/media/uapi/mediactl/media-request-ioc-queue.rst
new file mode 100644
index ..d3bac7b70422
--- /dev/null
+++ b/Documentation/media/uapi/mediactl/media-request-ioc-queue.rst
@@ -0,0 +1,50 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+.. _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 `, then
+this request ioctl
