* [PATCH 0/3] Documentation cleanups
@ 2019-01-22 11:27 hverkuil-cisco
2019-01-22 11:27 ` [PATCH 1/3] dev-effect.rst: remove unused Effect Interface chapter hverkuil-cisco
` (2 more replies)
0 siblings, 3 replies; 9+ messages in thread
From: hverkuil-cisco @ 2019-01-22 11:27 UTC (permalink / raw)
To: linux-media; +Cc: Tomasz Figa, Alexandre Courbot
From: Hans Verkuil <hverkuil-cisco@xs4all.nl>
Drop the obsolete Effect and Teletext interfaces. Rename the
Codec Interface to Video Memory To Memory Interface, which is
more accurate.
This also makes more sense when the detailed codec APIs are
added.
Regards,
Hans
Hans Verkuil (3):
dev-effect.rst: remove unused Effect Interface chapter
dev-teletext.rst: remove obsolete teletext interface
Documentation/media: rename "Codec Interface"
.../media/uapi/mediactl/request-api.rst | 4 +-
Documentation/media/uapi/v4l/dev-effect.rst | 28 -------------
.../v4l/{dev-codec.rst => dev-mem2mem.rst} | 21 ++++------
Documentation/media/uapi/v4l/dev-teletext.rst | 41 -------------------
Documentation/media/uapi/v4l/devices.rst | 4 +-
.../media/uapi/v4l/pixfmt-compressed.rst | 2 +-
Documentation/media/uapi/v4l/vidioc-qbuf.rst | 2 +-
7 files changed, 13 insertions(+), 89 deletions(-)
delete mode 100644 Documentation/media/uapi/v4l/dev-effect.rst
rename Documentation/media/uapi/v4l/{dev-codec.rst => dev-mem2mem.rst} (79%)
delete mode 100644 Documentation/media/uapi/v4l/dev-teletext.rst
--
2.20.1
^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH 1/3] dev-effect.rst: remove unused Effect Interface chapter
2019-01-22 11:27 [PATCH 0/3] Documentation cleanups hverkuil-cisco
@ 2019-01-22 11:27 ` hverkuil-cisco
2019-01-22 11:27 ` [PATCH 2/3] dev-teletext.rst: remove obsolete teletext interface hverkuil-cisco
2019-01-22 11:27 ` [PATCH 3/3] Documentation/media: rename "Codec Interface" hverkuil-cisco
2 siblings, 0 replies; 9+ messages in thread
From: hverkuil-cisco @ 2019-01-22 11:27 UTC (permalink / raw)
To: linux-media; +Cc: Tomasz Figa, Alexandre Courbot, Hans Verkuil
From: Hans Verkuil <hverkuil-cisco@xs4all.nl>
We never had an effect interface, and if you want to do such
things you use the mem2mem interface instead.
Just drop this from the spec.
Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
---
Documentation/media/uapi/v4l/dev-effect.rst | 28 ---------------------
Documentation/media/uapi/v4l/devices.rst | 1 -
2 files changed, 29 deletions(-)
delete mode 100644 Documentation/media/uapi/v4l/dev-effect.rst
diff --git a/Documentation/media/uapi/v4l/dev-effect.rst b/Documentation/media/uapi/v4l/dev-effect.rst
deleted file mode 100644
index b165e2c20910..000000000000
--- a/Documentation/media/uapi/v4l/dev-effect.rst
+++ /dev/null
@@ -1,28 +0,0 @@
-.. Permission is granted to copy, distribute and/or modify this
-.. document under the terms of the GNU Free Documentation License,
-.. Version 1.1 or any later version published by the Free Software
-.. Foundation, with no Invariant Sections, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/media/uapi/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _effect:
-
-************************
-Effect Devices Interface
-************************
-
-.. note::
- This interface has been be suspended from the V4L2 API.
- The implementation for such effects should be done
- via mem2mem devices.
-
-A V4L2 video effect device can do image effects, filtering, or combine
-two or more images or image streams. For example video transitions or
-wipes. Applications send data to be processed and receive the result
-data either with :ref:`read() <func-read>` and
-:ref:`write() <func-write>` functions, or through the streaming I/O
-mechanism.
-
-[to do]
diff --git a/Documentation/media/uapi/v4l/devices.rst b/Documentation/media/uapi/v4l/devices.rst
index 5dbe9d13b6e6..c959c0443c2f 100644
--- a/Documentation/media/uapi/v4l/devices.rst
+++ b/Documentation/media/uapi/v4l/devices.rst
@@ -22,7 +22,6 @@ Interfaces
dev-output
dev-osd
dev-codec
- dev-effect
dev-raw-vbi
dev-sliced-vbi
dev-teletext
--
2.20.1
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [PATCH 2/3] dev-teletext.rst: remove obsolete teletext interface
2019-01-22 11:27 [PATCH 0/3] Documentation cleanups hverkuil-cisco
2019-01-22 11:27 ` [PATCH 1/3] dev-effect.rst: remove unused Effect Interface chapter hverkuil-cisco
@ 2019-01-22 11:27 ` hverkuil-cisco
2019-01-22 11:27 ` [PATCH 3/3] Documentation/media: rename "Codec Interface" hverkuil-cisco
2 siblings, 0 replies; 9+ messages in thread
From: hverkuil-cisco @ 2019-01-22 11:27 UTC (permalink / raw)
To: linux-media; +Cc: Tomasz Figa, Alexandre Courbot, Hans Verkuil
From: Hans Verkuil <hverkuil-cisco@xs4all.nl>
The teletext interface has been dead for years now, just
remove it.
Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
---
Documentation/media/uapi/v4l/dev-teletext.rst | 41 -------------------
Documentation/media/uapi/v4l/devices.rst | 1 -
2 files changed, 42 deletions(-)
delete mode 100644 Documentation/media/uapi/v4l/dev-teletext.rst
diff --git a/Documentation/media/uapi/v4l/dev-teletext.rst b/Documentation/media/uapi/v4l/dev-teletext.rst
deleted file mode 100644
index 35e8c4b35458..000000000000
--- a/Documentation/media/uapi/v4l/dev-teletext.rst
+++ /dev/null
@@ -1,41 +0,0 @@
-.. Permission is granted to copy, distribute and/or modify this
-.. document under the terms of the GNU Free Documentation License,
-.. Version 1.1 or any later version published by the Free Software
-.. Foundation, with no Invariant Sections, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/media/uapi/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _ttx:
-
-******************
-Teletext Interface
-******************
-
-This interface was aimed at devices receiving and demodulating Teletext
-data [:ref:`ets300706`, :ref:`itu653`], evaluating the Teletext
-packages and storing formatted pages in cache memory. Such devices are
-usually implemented as microcontrollers with serial interface
-(I\ :sup:`2`\ C) and could be found on old TV cards, dedicated Teletext
-decoding cards and home-brew devices connected to the PC parallel port.
-
-The Teletext API was designed by Martin Buck. It was defined in the
-kernel header file ``linux/videotext.h``, the specification is available
-from
-`ftp://ftp.gwdg.de/pub/linux/misc/videotext/ <ftp://ftp.gwdg.de/pub/linux/misc/videotext/>`__.
-(Videotext is the name of the German public television Teletext
-service.)
-
-Eventually the Teletext API was integrated into the V4L API with
-character device file names ``/dev/vtx0`` to ``/dev/vtx31``, device
-major number 81, minor numbers 192 to 223.
-
-However, teletext decoders were quickly replaced by more generic VBI
-demodulators and those dedicated teletext decoders no longer exist. For
-many years the vtx devices were still around, even though nobody used
-them. So the decision was made to finally remove support for the
-Teletext API in kernel 2.6.37.
-
-Modern devices all use the :ref:`raw <raw-vbi>` or
-:ref:`sliced` VBI API.
diff --git a/Documentation/media/uapi/v4l/devices.rst b/Documentation/media/uapi/v4l/devices.rst
index c959c0443c2f..d6fcf3db5909 100644
--- a/Documentation/media/uapi/v4l/devices.rst
+++ b/Documentation/media/uapi/v4l/devices.rst
@@ -24,7 +24,6 @@ Interfaces
dev-codec
dev-raw-vbi
dev-sliced-vbi
- dev-teletext
dev-radio
dev-rds
dev-sdr
--
2.20.1
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [PATCH 3/3] Documentation/media: rename "Codec Interface"
2019-01-22 11:27 [PATCH 0/3] Documentation cleanups hverkuil-cisco
2019-01-22 11:27 ` [PATCH 1/3] dev-effect.rst: remove unused Effect Interface chapter hverkuil-cisco
2019-01-22 11:27 ` [PATCH 2/3] dev-teletext.rst: remove obsolete teletext interface hverkuil-cisco
@ 2019-01-22 11:27 ` hverkuil-cisco
2019-01-23 3:17 ` Tomasz Figa
2019-01-23 8:07 ` [PATCHv2 " Hans Verkuil
2 siblings, 2 replies; 9+ messages in thread
From: hverkuil-cisco @ 2019-01-22 11:27 UTC (permalink / raw)
To: linux-media; +Cc: Tomasz Figa, Alexandre Courbot, Hans Verkuil
From: Hans Verkuil <hverkuil-cisco@xs4all.nl>
The "Codec Interface" chapter is poorly named since codecs are just one
use-case of the Memory-to-Memory Interface. Rename it and clean up the
text a bit.
Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
---
.../media/uapi/mediactl/request-api.rst | 4 ++--
.../v4l/{dev-codec.rst => dev-mem2mem.rst} | 21 +++++++------------
Documentation/media/uapi/v4l/devices.rst | 2 +-
.../media/uapi/v4l/pixfmt-compressed.rst | 2 +-
Documentation/media/uapi/v4l/vidioc-qbuf.rst | 2 +-
5 files changed, 13 insertions(+), 18 deletions(-)
rename Documentation/media/uapi/v4l/{dev-codec.rst => dev-mem2mem.rst} (79%)
diff --git a/Documentation/media/uapi/mediactl/request-api.rst b/Documentation/media/uapi/mediactl/request-api.rst
index 4b25ad03f45a..1ad631e549fe 100644
--- a/Documentation/media/uapi/mediactl/request-api.rst
+++ b/Documentation/media/uapi/mediactl/request-api.rst
@@ -91,7 +91,7 @@ A request must contain at least one buffer, otherwise ``ENOENT`` is returned.
A queued request cannot be modified anymore.
.. caution::
- For :ref:`memory-to-memory devices <codec>` you can use requests only for
+ For :ref:`memory-to-memory devices <mem2mem>` you can use requests only for
output buffers, not for capture buffers. Attempting to add a capture buffer
to a request will result in an ``EACCES`` error.
@@ -152,7 +152,7 @@ if it had just been allocated.
Example for a Codec Device
--------------------------
-For use-cases such as :ref:`codecs <codec>`, the request API can be used
+For use-cases such as :ref:`codecs <mem2mem>`, the request API can be used
to associate specific controls to
be applied by the driver for the OUTPUT buffer, allowing user-space
to queue many such buffers in advance. It can also take advantage of requests'
diff --git a/Documentation/media/uapi/v4l/dev-codec.rst b/Documentation/media/uapi/v4l/dev-mem2mem.rst
similarity index 79%
rename from Documentation/media/uapi/v4l/dev-codec.rst
rename to Documentation/media/uapi/v4l/dev-mem2mem.rst
index b5e017c17834..69efcc747588 100644
--- a/Documentation/media/uapi/v4l/dev-codec.rst
+++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst
@@ -7,11 +7,11 @@
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-.. _codec:
+.. _mem2mem:
-***************
-Codec Interface
-***************
+********************************
+Video Memory To Memory Interface
+********************************
A V4L2 codec can compress, decompress, transform, or otherwise convert
video data from one format into another format, in memory. Typically
@@ -25,19 +25,14 @@ memory) stream I/O. An application will have to setup the stream I/O for
both sides and finally call :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
for both capture and output to start the codec.
-Video compression codecs use the MPEG controls to setup their codec
-parameters
-
-.. note::
-
- The MPEG controls actually support many more codecs than
- just MPEG. See :ref:`mpeg-controls`.
+Video compression codecs use codec controls to setup their codec parameters.
+See :ref:`mpeg-controls`.
Memory-to-memory devices function as a shared resource: you can
open the video node multiple times, each application setting up their
-own codec properties that are local to the file handle, and each can use
+own properties that are local to the file handle, and each can use
it independently from the others. The driver will arbitrate access to
-the codec and reprogram it whenever another file handler gets access.
+the hardware and reprogram it whenever another file handler gets access.
This is different from the usual video node behavior where the video
properties are global to the device (i.e. changing something through one
file handle is visible through another file handle).
diff --git a/Documentation/media/uapi/v4l/devices.rst b/Documentation/media/uapi/v4l/devices.rst
index d6fcf3db5909..07f8d047662b 100644
--- a/Documentation/media/uapi/v4l/devices.rst
+++ b/Documentation/media/uapi/v4l/devices.rst
@@ -21,7 +21,7 @@ Interfaces
dev-overlay
dev-output
dev-osd
- dev-codec
+ dev-mem2mem
dev-raw-vbi
dev-sliced-vbi
dev-radio
diff --git a/Documentation/media/uapi/v4l/pixfmt-compressed.rst b/Documentation/media/uapi/v4l/pixfmt-compressed.rst
index e4c5e456df59..2675bef3eefe 100644
--- a/Documentation/media/uapi/v4l/pixfmt-compressed.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-compressed.rst
@@ -73,7 +73,7 @@ Compressed Formats
- 'MG2S'
- MPEG-2 parsed slice data, as extracted from the MPEG-2 bitstream.
This format is adapted for stateless video decoders that implement a
- MPEG-2 pipeline (using the :ref:`codec` and :ref:`media-request-api`).
+ MPEG-2 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`).
Metadata associated with the frame to decode is required to be passed
through the ``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS`` control and
quantization matrices can optionally be specified through the
diff --git a/Documentation/media/uapi/v4l/vidioc-qbuf.rst b/Documentation/media/uapi/v4l/vidioc-qbuf.rst
index 3259168a7358..c138d149faea 100644
--- a/Documentation/media/uapi/v4l/vidioc-qbuf.rst
+++ b/Documentation/media/uapi/v4l/vidioc-qbuf.rst
@@ -123,7 +123,7 @@ then ``EINVAL`` will be returned.
:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or calling :ref:`VIDIOC_REQBUFS`
the check for this will be reset.
- For :ref:`memory-to-memory devices <codec>` you can specify the
+ For :ref:`memory-to-memory devices <mem2mem>` you can specify the
``request_fd`` only for output buffers, not for capture buffers. Attempting
to specify this for a capture buffer will result in an ``EACCES`` error.
--
2.20.1
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH 3/3] Documentation/media: rename "Codec Interface"
2019-01-22 11:27 ` [PATCH 3/3] Documentation/media: rename "Codec Interface" hverkuil-cisco
@ 2019-01-23 3:17 ` Tomasz Figa
2019-01-23 3:46 ` Tomasz Figa
2019-01-23 8:07 ` [PATCHv2 " Hans Verkuil
1 sibling, 1 reply; 9+ messages in thread
From: Tomasz Figa @ 2019-01-23 3:17 UTC (permalink / raw)
To: Hans Verkuil, Alexandre Courbot; +Cc: Linux Media Mailing List
Hi Hans,
On Tue, Jan 22, 2019 at 8:27 PM <hverkuil-cisco@xs4all.nl> wrote:
>
> From: Hans Verkuil <hverkuil-cisco@xs4all.nl>
>
> The "Codec Interface" chapter is poorly named since codecs are just one
> use-case of the Memory-to-Memory Interface. Rename it and clean up the
> text a bit.
>
> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
> ---
> .../media/uapi/mediactl/request-api.rst | 4 ++--
> .../v4l/{dev-codec.rst => dev-mem2mem.rst} | 21 +++++++------------
> Documentation/media/uapi/v4l/devices.rst | 2 +-
> .../media/uapi/v4l/pixfmt-compressed.rst | 2 +-
> Documentation/media/uapi/v4l/vidioc-qbuf.rst | 2 +-
> 5 files changed, 13 insertions(+), 18 deletions(-)
> rename Documentation/media/uapi/v4l/{dev-codec.rst => dev-mem2mem.rst} (79%)
>
Thanks for this cleanup! Indeed it makes much more sense with your
changes. Some comments inline.
> diff --git a/Documentation/media/uapi/mediactl/request-api.rst b/Documentation/media/uapi/mediactl/request-api.rst
> index 4b25ad03f45a..1ad631e549fe 100644
> --- a/Documentation/media/uapi/mediactl/request-api.rst
> +++ b/Documentation/media/uapi/mediactl/request-api.rst
> @@ -91,7 +91,7 @@ A request must contain at least one buffer, otherwise ``ENOENT`` is returned.
> A queued request cannot be modified anymore.
>
> .. caution::
> - For :ref:`memory-to-memory devices <codec>` you can use requests only for
> + For :ref:`memory-to-memory devices <mem2mem>` you can use requests only for
> output buffers, not for capture buffers. Attempting to add a capture buffer
> to a request will result in an ``EACCES`` error.
>
> @@ -152,7 +152,7 @@ if it had just been allocated.
> Example for a Codec Device
> --------------------------
>
> -For use-cases such as :ref:`codecs <codec>`, the request API can be used
> +For use-cases such as :ref:`codecs <mem2mem>`, the request API can be used
I guess this should eventually be made to point to the codec sections.
Alex, perhaps it would make sense to do it in your documentation
patch.
> to associate specific controls to
> be applied by the driver for the OUTPUT buffer, allowing user-space
> to queue many such buffers in advance. It can also take advantage of requests'
> diff --git a/Documentation/media/uapi/v4l/dev-codec.rst b/Documentation/media/uapi/v4l/dev-mem2mem.rst
> similarity index 79%
> rename from Documentation/media/uapi/v4l/dev-codec.rst
> rename to Documentation/media/uapi/v4l/dev-mem2mem.rst
> index b5e017c17834..69efcc747588 100644
> --- a/Documentation/media/uapi/v4l/dev-codec.rst
> +++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst
> @@ -7,11 +7,11 @@
> ..
> .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
>
> -.. _codec:
> +.. _mem2mem:
>
> -***************
> -Codec Interface
> -***************
> +********************************
> +Video Memory To Memory Interface
> +********************************
>
> A V4L2 codec can compress, decompress, transform, or otherwise convert
Codec still left here.
> video data from one format into another format, in memory. Typically
> @@ -25,19 +25,14 @@ memory) stream I/O. An application will have to setup the stream I/O for
> both sides and finally call :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
> for both capture and output to start the codec.
Ditto.
>
> -Video compression codecs use the MPEG controls to setup their codec
> -parameters
> -
> -.. note::
> -
> - The MPEG controls actually support many more codecs than
> - just MPEG. See :ref:`mpeg-controls`.
> +Video compression codecs use codec controls to setup their codec parameters.
> +See :ref:`mpeg-controls`.
>
> Memory-to-memory devices function as a shared resource: you can
> open the video node multiple times, each application setting up their
> -own codec properties that are local to the file handle, and each can use
> +own properties that are local to the file handle, and each can use
> it independently from the others. The driver will arbitrate access to
> -the codec and reprogram it whenever another file handler gets access.
> +the hardware and reprogram it whenever another file handler gets access.
> This is different from the usual video node behavior where the video
> properties are global to the device (i.e. changing something through one
> file handle is visible through another file handle).
> diff --git a/Documentation/media/uapi/v4l/devices.rst b/Documentation/media/uapi/v4l/devices.rst
> index d6fcf3db5909..07f8d047662b 100644
> --- a/Documentation/media/uapi/v4l/devices.rst
> +++ b/Documentation/media/uapi/v4l/devices.rst
> @@ -21,7 +21,7 @@ Interfaces
> dev-overlay
> dev-output
> dev-osd
> - dev-codec
> + dev-mem2mem
> dev-raw-vbi
> dev-sliced-vbi
> dev-radio
> diff --git a/Documentation/media/uapi/v4l/pixfmt-compressed.rst b/Documentation/media/uapi/v4l/pixfmt-compressed.rst
> index e4c5e456df59..2675bef3eefe 100644
> --- a/Documentation/media/uapi/v4l/pixfmt-compressed.rst
> +++ b/Documentation/media/uapi/v4l/pixfmt-compressed.rst
> @@ -73,7 +73,7 @@ Compressed Formats
> - 'MG2S'
> - MPEG-2 parsed slice data, as extracted from the MPEG-2 bitstream.
> This format is adapted for stateless video decoders that implement a
> - MPEG-2 pipeline (using the :ref:`codec` and :ref:`media-request-api`).
> + MPEG-2 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`).
Reference to be updated later too.
Best regards,
Tomasz
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH 3/3] Documentation/media: rename "Codec Interface"
2019-01-23 3:17 ` Tomasz Figa
@ 2019-01-23 3:46 ` Tomasz Figa
0 siblings, 0 replies; 9+ messages in thread
From: Tomasz Figa @ 2019-01-23 3:46 UTC (permalink / raw)
To: Hans Verkuil, Alexandre Courbot; +Cc: Linux Media Mailing List
On Wed, Jan 23, 2019 at 12:17 PM Tomasz Figa <tfiga@chromium.org> wrote:
>
> Hi Hans,
>
> On Tue, Jan 22, 2019 at 8:27 PM <hverkuil-cisco@xs4all.nl> wrote:
> >
> > From: Hans Verkuil <hverkuil-cisco@xs4all.nl>
> >
> > The "Codec Interface" chapter is poorly named since codecs are just one
> > use-case of the Memory-to-Memory Interface. Rename it and clean up the
> > text a bit.
> >
> > Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
> > ---
> > .../media/uapi/mediactl/request-api.rst | 4 ++--
> > .../v4l/{dev-codec.rst => dev-mem2mem.rst} | 21 +++++++------------
> > Documentation/media/uapi/v4l/devices.rst | 2 +-
> > .../media/uapi/v4l/pixfmt-compressed.rst | 2 +-
> > Documentation/media/uapi/v4l/vidioc-qbuf.rst | 2 +-
> > 5 files changed, 13 insertions(+), 18 deletions(-)
> > rename Documentation/media/uapi/v4l/{dev-codec.rst => dev-mem2mem.rst} (79%)
> >
>
> Thanks for this cleanup! Indeed it makes much more sense with your
> changes. Some comments inline.
>
> > diff --git a/Documentation/media/uapi/mediactl/request-api.rst b/Documentation/media/uapi/mediactl/request-api.rst
> > index 4b25ad03f45a..1ad631e549fe 100644
> > --- a/Documentation/media/uapi/mediactl/request-api.rst
> > +++ b/Documentation/media/uapi/mediactl/request-api.rst
> > @@ -91,7 +91,7 @@ A request must contain at least one buffer, otherwise ``ENOENT`` is returned.
> > A queued request cannot be modified anymore.
> >
> > .. caution::
> > - For :ref:`memory-to-memory devices <codec>` you can use requests only for
> > + For :ref:`memory-to-memory devices <mem2mem>` you can use requests only for
> > output buffers, not for capture buffers. Attempting to add a capture buffer
> > to a request will result in an ``EACCES`` error.
> >
> > @@ -152,7 +152,7 @@ if it had just been allocated.
> > Example for a Codec Device
> > --------------------------
> >
> > -For use-cases such as :ref:`codecs <codec>`, the request API can be used
> > +For use-cases such as :ref:`codecs <mem2mem>`, the request API can be used
>
> I guess this should eventually be made to point to the codec sections.
> Alex, perhaps it would make sense to do it in your documentation
> patch.
>
> > to associate specific controls to
> > be applied by the driver for the OUTPUT buffer, allowing user-space
> > to queue many such buffers in advance. It can also take advantage of requests'
> > diff --git a/Documentation/media/uapi/v4l/dev-codec.rst b/Documentation/media/uapi/v4l/dev-mem2mem.rst
> > similarity index 79%
> > rename from Documentation/media/uapi/v4l/dev-codec.rst
> > rename to Documentation/media/uapi/v4l/dev-mem2mem.rst
> > index b5e017c17834..69efcc747588 100644
> > --- a/Documentation/media/uapi/v4l/dev-codec.rst
> > +++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst
> > @@ -7,11 +7,11 @@
> > ..
> > .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
> >
> > -.. _codec:
> > +.. _mem2mem:
> >
> > -***************
> > -Codec Interface
> > -***************
> > +********************************
> > +Video Memory To Memory Interface
> > +********************************
> >
Also to bikeshed a bit, the text seems to follow the
"memory-to-memory" convention, so perhaps "Video Memory-to-memory
Interface" would be more consistent?
Best regards,
Tomasz
^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCHv2 3/3] Documentation/media: rename "Codec Interface"
2019-01-22 11:27 ` [PATCH 3/3] Documentation/media: rename "Codec Interface" hverkuil-cisco
2019-01-23 3:17 ` Tomasz Figa
@ 2019-01-23 8:07 ` Hans Verkuil
2019-01-24 5:35 ` Tomasz Figa
2019-01-25 6:31 ` Alexandre Courbot
1 sibling, 2 replies; 9+ messages in thread
From: Hans Verkuil @ 2019-01-23 8:07 UTC (permalink / raw)
To: linux-media; +Cc: Tomasz Figa, Alexandre Courbot
The "Codec Interface" chapter is poorly named since codecs are just one
use-case of the Memory-to-Memory Interface. Rename it and clean up the
text a bit.
Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
---
Incorporated Tomasz' comments.
Note that I moved the section about codec controls to the end. The idea
is that when we add the codec specs this section is updated and the
links to those specs is added there.
---
.../media/uapi/mediactl/request-api.rst | 4 +-
.../v4l/{dev-codec.rst => dev-mem2mem.rst} | 41 +++++++++----------
Documentation/media/uapi/v4l/devices.rst | 2 +-
.../media/uapi/v4l/pixfmt-compressed.rst | 2 +-
Documentation/media/uapi/v4l/vidioc-qbuf.rst | 2 +-
5 files changed, 25 insertions(+), 26 deletions(-)
rename Documentation/media/uapi/v4l/{dev-codec.rst => dev-mem2mem.rst} (50%)
diff --git a/Documentation/media/uapi/mediactl/request-api.rst b/Documentation/media/uapi/mediactl/request-api.rst
index 4b25ad03f45a..1ad631e549fe 100644
--- a/Documentation/media/uapi/mediactl/request-api.rst
+++ b/Documentation/media/uapi/mediactl/request-api.rst
@@ -91,7 +91,7 @@ A request must contain at least one buffer, otherwise ``ENOENT`` is returned.
A queued request cannot be modified anymore.
.. caution::
- For :ref:`memory-to-memory devices <codec>` you can use requests only for
+ For :ref:`memory-to-memory devices <mem2mem>` you can use requests only for
output buffers, not for capture buffers. Attempting to add a capture buffer
to a request will result in an ``EACCES`` error.
@@ -152,7 +152,7 @@ if it had just been allocated.
Example for a Codec Device
--------------------------
-For use-cases such as :ref:`codecs <codec>`, the request API can be used
+For use-cases such as :ref:`codecs <mem2mem>`, the request API can be used
to associate specific controls to
be applied by the driver for the OUTPUT buffer, allowing user-space
to queue many such buffers in advance. It can also take advantage of requests'
diff --git a/Documentation/media/uapi/v4l/dev-codec.rst b/Documentation/media/uapi/v4l/dev-mem2mem.rst
similarity index 50%
rename from Documentation/media/uapi/v4l/dev-codec.rst
rename to Documentation/media/uapi/v4l/dev-mem2mem.rst
index b5e017c17834..67a980818dc8 100644
--- a/Documentation/media/uapi/v4l/dev-codec.rst
+++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst
@@ -7,37 +7,36 @@
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-.. _codec:
+.. _mem2mem:
-***************
-Codec Interface
-***************
+********************************
+Video Memory-To-Memory Interface
+********************************
-A V4L2 codec can compress, decompress, transform, or otherwise convert
-video data from one format into another format, in memory. Typically
-such devices are memory-to-memory devices (i.e. devices with the
-``V4L2_CAP_VIDEO_M2M`` or ``V4L2_CAP_VIDEO_M2M_MPLANE`` capability set).
+A V4L2 memory-to-memory device can compress, decompress, transform, or
+otherwise convert video data from one format into another format, in memory.
+Such memory-to-memory devices set the ``V4L2_CAP_VIDEO_M2M`` or
+``V4L2_CAP_VIDEO_M2M_MPLANE`` capability. Examples of memory-to-memory
+devices are codecs, scalers, deinterlacers or format converters (i.e.
+converting from YUV to RGB).
A memory-to-memory video node acts just like a normal video node, but it
-supports both output (sending frames from memory to the codec hardware)
-and capture (receiving the processed frames from the codec hardware into
+supports both output (sending frames from memory to the hardware)
+and capture (receiving the processed frames from the hardware into
memory) stream I/O. An application will have to setup the stream I/O for
both sides and finally call :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
-for both capture and output to start the codec.
-
-Video compression codecs use the MPEG controls to setup their codec
-parameters
-
-.. note::
-
- The MPEG controls actually support many more codecs than
- just MPEG. See :ref:`mpeg-controls`.
+for both capture and output to start the hardware.
Memory-to-memory devices function as a shared resource: you can
open the video node multiple times, each application setting up their
-own codec properties that are local to the file handle, and each can use
+own properties that are local to the file handle, and each can use
it independently from the others. The driver will arbitrate access to
-the codec and reprogram it whenever another file handler gets access.
+the hardware and reprogram it whenever another file handler gets access.
This is different from the usual video node behavior where the video
properties are global to the device (i.e. changing something through one
file handle is visible through another file handle).
+
+One of the most common memory-to-memory device is the codec. Codecs
+are more complicated than most and require additional setup for
+their codec parameters. This is done through codec controls.
+See :ref:`mpeg-controls`.
diff --git a/Documentation/media/uapi/v4l/devices.rst b/Documentation/media/uapi/v4l/devices.rst
index d6fcf3db5909..07f8d047662b 100644
--- a/Documentation/media/uapi/v4l/devices.rst
+++ b/Documentation/media/uapi/v4l/devices.rst
@@ -21,7 +21,7 @@ Interfaces
dev-overlay
dev-output
dev-osd
- dev-codec
+ dev-mem2mem
dev-raw-vbi
dev-sliced-vbi
dev-radio
diff --git a/Documentation/media/uapi/v4l/pixfmt-compressed.rst b/Documentation/media/uapi/v4l/pixfmt-compressed.rst
index e4c5e456df59..2675bef3eefe 100644
--- a/Documentation/media/uapi/v4l/pixfmt-compressed.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-compressed.rst
@@ -73,7 +73,7 @@ Compressed Formats
- 'MG2S'
- MPEG-2 parsed slice data, as extracted from the MPEG-2 bitstream.
This format is adapted for stateless video decoders that implement a
- MPEG-2 pipeline (using the :ref:`codec` and :ref:`media-request-api`).
+ MPEG-2 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`).
Metadata associated with the frame to decode is required to be passed
through the ``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS`` control and
quantization matrices can optionally be specified through the
diff --git a/Documentation/media/uapi/v4l/vidioc-qbuf.rst b/Documentation/media/uapi/v4l/vidioc-qbuf.rst
index 3259168a7358..c138d149faea 100644
--- a/Documentation/media/uapi/v4l/vidioc-qbuf.rst
+++ b/Documentation/media/uapi/v4l/vidioc-qbuf.rst
@@ -123,7 +123,7 @@ then ``EINVAL`` will be returned.
:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or calling :ref:`VIDIOC_REQBUFS`
the check for this will be reset.
- For :ref:`memory-to-memory devices <codec>` you can specify the
+ For :ref:`memory-to-memory devices <mem2mem>` you can specify the
``request_fd`` only for output buffers, not for capture buffers. Attempting
to specify this for a capture buffer will result in an ``EACCES`` error.
--
2.20.1
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCHv2 3/3] Documentation/media: rename "Codec Interface"
2019-01-23 8:07 ` [PATCHv2 " Hans Verkuil
@ 2019-01-24 5:35 ` Tomasz Figa
2019-01-25 6:31 ` Alexandre Courbot
1 sibling, 0 replies; 9+ messages in thread
From: Tomasz Figa @ 2019-01-24 5:35 UTC (permalink / raw)
To: Hans Verkuil; +Cc: Linux Media Mailing List, Alexandre Courbot
Hi Hans,
On Wed, Jan 23, 2019 at 5:07 PM Hans Verkuil <hverkuil-cisco@xs4all.nl> wrote:
>
> The "Codec Interface" chapter is poorly named since codecs are just one
> use-case of the Memory-to-Memory Interface. Rename it and clean up the
> text a bit.
>
> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
> ---
> Incorporated Tomasz' comments.
>
> Note that I moved the section about codec controls to the end. The idea
> is that when we add the codec specs this section is updated and the
> links to those specs is added there.
> ---
> .../media/uapi/mediactl/request-api.rst | 4 +-
> .../v4l/{dev-codec.rst => dev-mem2mem.rst} | 41 +++++++++----------
> Documentation/media/uapi/v4l/devices.rst | 2 +-
> .../media/uapi/v4l/pixfmt-compressed.rst | 2 +-
> Documentation/media/uapi/v4l/vidioc-qbuf.rst | 2 +-
> 5 files changed, 25 insertions(+), 26 deletions(-)
> rename Documentation/media/uapi/v4l/{dev-codec.rst => dev-mem2mem.rst} (50%)
>
Thanks a lot!
Reviewed-by: Tomasz Figa <tfiga@chromium.org>
Best regards,
Tomasz
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCHv2 3/3] Documentation/media: rename "Codec Interface"
2019-01-23 8:07 ` [PATCHv2 " Hans Verkuil
2019-01-24 5:35 ` Tomasz Figa
@ 2019-01-25 6:31 ` Alexandre Courbot
1 sibling, 0 replies; 9+ messages in thread
From: Alexandre Courbot @ 2019-01-25 6:31 UTC (permalink / raw)
To: Hans Verkuil; +Cc: Linux Media Mailing List, Tomasz Figa
On Wed, Jan 23, 2019 at 5:07 PM Hans Verkuil <hverkuil-cisco@xs4all.nl> wrote:
>
> The "Codec Interface" chapter is poorly named since codecs are just one
> use-case of the Memory-to-Memory Interface. Rename it and clean up the
> text a bit.
>
> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
> ---
> Incorporated Tomasz' comments.
>
> Note that I moved the section about codec controls to the end. The idea
> is that when we add the codec specs this section is updated and the
> links to those specs is added there.
Makes sense indeed!
Acked-by: Alexandre Courbot <acourbot@chromium.org>
> ---
> .../media/uapi/mediactl/request-api.rst | 4 +-
> .../v4l/{dev-codec.rst => dev-mem2mem.rst} | 41 +++++++++----------
> Documentation/media/uapi/v4l/devices.rst | 2 +-
> .../media/uapi/v4l/pixfmt-compressed.rst | 2 +-
> Documentation/media/uapi/v4l/vidioc-qbuf.rst | 2 +-
> 5 files changed, 25 insertions(+), 26 deletions(-)
> rename Documentation/media/uapi/v4l/{dev-codec.rst => dev-mem2mem.rst} (50%)
>
> diff --git a/Documentation/media/uapi/mediactl/request-api.rst b/Documentation/media/uapi/mediactl/request-api.rst
> index 4b25ad03f45a..1ad631e549fe 100644
> --- a/Documentation/media/uapi/mediactl/request-api.rst
> +++ b/Documentation/media/uapi/mediactl/request-api.rst
> @@ -91,7 +91,7 @@ A request must contain at least one buffer, otherwise ``ENOENT`` is returned.
> A queued request cannot be modified anymore.
>
> .. caution::
> - For :ref:`memory-to-memory devices <codec>` you can use requests only for
> + For :ref:`memory-to-memory devices <mem2mem>` you can use requests only for
> output buffers, not for capture buffers. Attempting to add a capture buffer
> to a request will result in an ``EACCES`` error.
>
> @@ -152,7 +152,7 @@ if it had just been allocated.
> Example for a Codec Device
> --------------------------
>
> -For use-cases such as :ref:`codecs <codec>`, the request API can be used
> +For use-cases such as :ref:`codecs <mem2mem>`, the request API can be used
> to associate specific controls to
> be applied by the driver for the OUTPUT buffer, allowing user-space
> to queue many such buffers in advance. It can also take advantage of requests'
> diff --git a/Documentation/media/uapi/v4l/dev-codec.rst b/Documentation/media/uapi/v4l/dev-mem2mem.rst
> similarity index 50%
> rename from Documentation/media/uapi/v4l/dev-codec.rst
> rename to Documentation/media/uapi/v4l/dev-mem2mem.rst
> index b5e017c17834..67a980818dc8 100644
> --- a/Documentation/media/uapi/v4l/dev-codec.rst
> +++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst
> @@ -7,37 +7,36 @@
> ..
> .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
>
> -.. _codec:
> +.. _mem2mem:
>
> -***************
> -Codec Interface
> -***************
> +********************************
> +Video Memory-To-Memory Interface
> +********************************
>
> -A V4L2 codec can compress, decompress, transform, or otherwise convert
> -video data from one format into another format, in memory. Typically
> -such devices are memory-to-memory devices (i.e. devices with the
> -``V4L2_CAP_VIDEO_M2M`` or ``V4L2_CAP_VIDEO_M2M_MPLANE`` capability set).
> +A V4L2 memory-to-memory device can compress, decompress, transform, or
> +otherwise convert video data from one format into another format, in memory.
> +Such memory-to-memory devices set the ``V4L2_CAP_VIDEO_M2M`` or
> +``V4L2_CAP_VIDEO_M2M_MPLANE`` capability. Examples of memory-to-memory
> +devices are codecs, scalers, deinterlacers or format converters (i.e.
> +converting from YUV to RGB).
>
> A memory-to-memory video node acts just like a normal video node, but it
> -supports both output (sending frames from memory to the codec hardware)
> -and capture (receiving the processed frames from the codec hardware into
> +supports both output (sending frames from memory to the hardware)
> +and capture (receiving the processed frames from the hardware into
> memory) stream I/O. An application will have to setup the stream I/O for
> both sides and finally call :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
> -for both capture and output to start the codec.
> -
> -Video compression codecs use the MPEG controls to setup their codec
> -parameters
> -
> -.. note::
> -
> - The MPEG controls actually support many more codecs than
> - just MPEG. See :ref:`mpeg-controls`.
> +for both capture and output to start the hardware.
>
> Memory-to-memory devices function as a shared resource: you can
> open the video node multiple times, each application setting up their
> -own codec properties that are local to the file handle, and each can use
> +own properties that are local to the file handle, and each can use
> it independently from the others. The driver will arbitrate access to
> -the codec and reprogram it whenever another file handler gets access.
> +the hardware and reprogram it whenever another file handler gets access.
> This is different from the usual video node behavior where the video
> properties are global to the device (i.e. changing something through one
> file handle is visible through another file handle).
> +
> +One of the most common memory-to-memory device is the codec. Codecs
> +are more complicated than most and require additional setup for
> +their codec parameters. This is done through codec controls.
> +See :ref:`mpeg-controls`.
> diff --git a/Documentation/media/uapi/v4l/devices.rst b/Documentation/media/uapi/v4l/devices.rst
> index d6fcf3db5909..07f8d047662b 100644
> --- a/Documentation/media/uapi/v4l/devices.rst
> +++ b/Documentation/media/uapi/v4l/devices.rst
> @@ -21,7 +21,7 @@ Interfaces
> dev-overlay
> dev-output
> dev-osd
> - dev-codec
> + dev-mem2mem
> dev-raw-vbi
> dev-sliced-vbi
> dev-radio
> diff --git a/Documentation/media/uapi/v4l/pixfmt-compressed.rst b/Documentation/media/uapi/v4l/pixfmt-compressed.rst
> index e4c5e456df59..2675bef3eefe 100644
> --- a/Documentation/media/uapi/v4l/pixfmt-compressed.rst
> +++ b/Documentation/media/uapi/v4l/pixfmt-compressed.rst
> @@ -73,7 +73,7 @@ Compressed Formats
> - 'MG2S'
> - MPEG-2 parsed slice data, as extracted from the MPEG-2 bitstream.
> This format is adapted for stateless video decoders that implement a
> - MPEG-2 pipeline (using the :ref:`codec` and :ref:`media-request-api`).
> + MPEG-2 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`).
> Metadata associated with the frame to decode is required to be passed
> through the ``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS`` control and
> quantization matrices can optionally be specified through the
> diff --git a/Documentation/media/uapi/v4l/vidioc-qbuf.rst b/Documentation/media/uapi/v4l/vidioc-qbuf.rst
> index 3259168a7358..c138d149faea 100644
> --- a/Documentation/media/uapi/v4l/vidioc-qbuf.rst
> +++ b/Documentation/media/uapi/v4l/vidioc-qbuf.rst
> @@ -123,7 +123,7 @@ then ``EINVAL`` will be returned.
> :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or calling :ref:`VIDIOC_REQBUFS`
> the check for this will be reset.
>
> - For :ref:`memory-to-memory devices <codec>` you can specify the
> + For :ref:`memory-to-memory devices <mem2mem>` you can specify the
> ``request_fd`` only for output buffers, not for capture buffers. Attempting
> to specify this for a capture buffer will result in an ``EACCES`` error.
>
> --
> 2.20.1
>
>
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2019-01-25 6:31 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-01-22 11:27 [PATCH 0/3] Documentation cleanups hverkuil-cisco
2019-01-22 11:27 ` [PATCH 1/3] dev-effect.rst: remove unused Effect Interface chapter hverkuil-cisco
2019-01-22 11:27 ` [PATCH 2/3] dev-teletext.rst: remove obsolete teletext interface hverkuil-cisco
2019-01-22 11:27 ` [PATCH 3/3] Documentation/media: rename "Codec Interface" hverkuil-cisco
2019-01-23 3:17 ` Tomasz Figa
2019-01-23 3:46 ` Tomasz Figa
2019-01-23 8:07 ` [PATCHv2 " Hans Verkuil
2019-01-24 5:35 ` Tomasz Figa
2019-01-25 6:31 ` Alexandre Courbot
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).