On 01/24/19 11:04, Tomasz Figa wrote: > Late happy new year everyone. It's been a while, but here is the v3 of > the stateful mem2mem codec interfaces documentation. Sorry for taking so > long time to respin. (Again.) > > This series attempts to add the documentation of what was discussed > during Media Workshops at LinuxCon Europe 2012 in Barcelona and then > later Embedded Linux Conference Europe 2014 in Düsseldorf and then > eventually written down by Pawel Osciak and tweaked a bit by Chrome OS > video team (but mostly in a cosmetic way or making the document more > precise), during the several years of Chrome OS using the APIs in > production. > > Note that most, if not all, of the API is already implemented in > existing mainline drivers, such as s5p-mfc or mtk-vcodec. Intention of > this series is just to formalize what we already have. > > Thanks everyone for the huge amount of useful comments for the RFC and > v1. Much of the credits should go to Pawel Osciak too, for writing most > of the original text of the initial RFC. Thank you very much for this v3. I've updated the spec with this v3 + Alexandre's v2 incorporated here: https://hverkuil.home.xs4all.nl/codec-api/uapi/v4l/dev-mem2mem.html I plan to review this as soon as I can because I really would like to get this merged for 5.1. Regards, Hans > > Changes since v2: > (https://lore.kernel.org/patchwork/cover/1002474/) > Decoder: > - Specified that the initial source change event is signaled > regardless of whether the client-set format matches the > stream format. > - Dropped V4L2_CID_MIN_BUFFERS_FOR_OUTPUT since it's meaningless > for the bitstream input buffers of decoders. > - Explicitly stated that VIDIOC_REQBUFS is not allowed on CAPTURE > if the stream information is not available. > - Described decode error handling. > - Mentioned that timestamps can be observed after a seek to > determine whether the CAPTURE buffers originated from before > or after the seek. > - Explicitly stated that after a pair of V4L2_DEC_CMD_STOP and > V4L2_DEC_CMD_START, the decoder is not reset and preserves > all the state. > > Encoder: > - Specified that width and height of CAPTURE format are ignored > and always zero. > - Explicitly noted the common use case for the CROP target with > macroblock-unaligned video resolutions. > - Added a reference to Request API. > - Dropped V4L2_CID_MIN_BUFFERS_FOR_CAPTURE since it's meaningless > for the bitstream output buffers of encoders. > - Explicitly stated that after a pair of V4L2_ENC_CMD_STOP and > V4L2_ENC_CMD_START, the encoder is not reset and preserves > all the state. > > General: > - Dropped format enumeration from "Initialization", since it's already > a part of "Querying capabilities". > - Many spelling, grammar, stylistic, etc. changes. > - Changed the style of note blocks. > - Rebased onto Hans' documentation cleanup series. > (https://patchwork.kernel.org/cover/10775407/ > https://patchwork.kernel.org/patch/10776737/) > - Moved the interfaces under the "Video Memory-To-Memory Interface" > section. > > For changes since v1 see the v2: > https://lore.kernel.org/patchwork/cover/1002474/ > > For changes since RFC see the v1: > https://patchwork.kernel.org/cover/10542207/ > > Tomasz Figa (2): > media: docs-rst: Document memory-to-memory video decoder interface > media: docs-rst: Document memory-to-memory video encoder interface > > Documentation/media/uapi/v4l/dev-decoder.rst | 1076 +++++++++++++++++ > Documentation/media/uapi/v4l/dev-encoder.rst | 586 +++++++++ > Documentation/media/uapi/v4l/dev-mem2mem.rst | 6 + > Documentation/media/uapi/v4l/pixfmt-v4l2.rst | 10 + > Documentation/media/uapi/v4l/v4l2.rst | 12 +- > .../media/uapi/v4l/vidioc-decoder-cmd.rst | 40 +- > .../media/uapi/v4l/vidioc-encoder-cmd.rst | 38 +- > Documentation/media/uapi/v4l/vidioc-g-fmt.rst | 14 + > 8 files changed, 1752 insertions(+), 30 deletions(-) > create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst > create mode 100644 Documentation/media/uapi/v4l/dev-encoder.rst >
