| Message ID | 20190122112727.12662-4-hverkuil-cisco@xs4all.nl (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Documentation cleanups | expand |
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
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
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.