DPB entry PicNum maximum value is 2*MaxFrameNum for interlaced
content (field_pic_flag=1).

As specified, MaxFrameNum is 2^(log2_max_frame_num_minus4 + 4)
and log2_max_frame_num_minus4 is in the range of 0 to 12,
which means pic_num should be a 32-bit field.

The v4l2_h264_dpb_entry struct needs to be padded to avoid a hole,
which might be also useful to allow future uAPI extensions.
Signed-off-by: NEzequiel Garcia <ezequiel@collabora.com>
Tested-by: NJonas Karlman <jonas@kwiboo.se>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>

As discussed recently, the current interface for the
Decoded Picture Buffer is not enough to properly
support field coding.

This commit introduces enough semantics to support
frame and field coding, and to signal how DPB entries
are "used for reference".

Reserved fields will be added by a follow-up commit.
Signed-off-by: NEzequiel Garcia <ezequiel@collabora.com>
Tested-by: NJonas Karlman <jonas@kwiboo.se>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>

Slice header syntax element 'first_mb_in_slice' can point
to the last macroblock, currently the field can only reference
65536 macroblocks which is insufficient for 8K videos.

Although unlikely, a 8192x4320 video (where macroblocks are 16x16),
would contain 138240 macroblocks on a frame.

As per the H264 specification, 'first_mb_in_slice' can be up to
PicSizeInMbs - 1, so increase the size of the field to 32-bits.

Note that v4l2_ctrl_h264_slice_params struct will be modified
in a follow-up commit, and so we defer its 64-bit padding.
Signed-off-by: NEzequiel Garcia <ezequiel@collabora.com>
Tested-by: NJonas Karlman <jonas@kwiboo.se>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>

Since pic_order_cnt_bit_size is not a syntax element itself, explicitly
state that it is the total size in bits of the pic_order_cnt_lsb,
delta_pic_order_cnt_bottom, delta_pic_order_cnt[0], and
delta_pic_order_cnt[1] syntax elements contained in the slice.

[Ezequiel: rebase]
Signed-off-by: NPhilipp Zabel <p.zabel@pengutronix.de>
Signed-off-by: NEzequiel Garcia <ezequiel@collabora.com>
Reviewed-by: NNicolas Dufresne <nicolas.dufresne@collabora.com>
Tested-by: NJonas Karlman <jonas@kwiboo.se>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>

The prediction weight parameters are only required under
certain conditions, which depend on slice header parameters.

As specified in section 7.3.3 Slice header syntax, the prediction
weight table is present if:

((weighted_pred_flag && (slice_type == P || slice_type == SP)) || \
(weighted_bipred_idc == 1 && slice_type == B))

Given its size, it makes sense to move this table to its control,
so applications can avoid passing it if the slice doesn't specify it.

Before this change struct v4l2_ctrl_h264_slice_params was 960 bytes.
With this change, it's 188 bytes and struct v4l2_ctrl_h264_pred_weight
is 772 bytes.
Signed-off-by: NEzequiel Garcia <ezequiel@collabora.com>
Tested-by: NJonas Karlman <jonas@kwiboo.se>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>

Commit 0b0393d5 ("media: uapi: h264: clarify
expected scaling_list_4x4/8x8 order") improved the
documentation on H264 scaling lists order.

This commit improves the documentation by clarifying
that the lists themselves are expected in raster scan order.
Signed-off-by: NEzequiel Garcia <ezequiel@collabora.com>
Tested-by: NJonas Karlman <jonas@kwiboo.se>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>

When dealing with interlaced frames, reference lists must tell if
each particular reference is meant for top or bottom field. This info
is currently not provided at all in the H264 related controls.

Change reference lists to hold a structure, which specifies
an index into the DPB array and the field/frame specification
for the picture.

Currently the only user of these lists is Cedrus which is just compile
fixed here. Actual usage of will come in a following commit.
Signed-off-by: NJernej Skrabec <jernej.skrabec@siol.net>
Signed-off-by: NEzequiel Garcia <ezequiel@collabora.com>
Tested-by: NJonas Karlman <jonas@kwiboo.se>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>

Add H264 profile "Contrained High" and H264 levels "5.2",
"6.0", "6.1" and "6.2".
Signed-off-by: NMaheshwar Ajja <majja@codeaurora.org>
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>

There are some uAPI stuff that are driver-specific. Add them
to the main media uAPI body.
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>

Most of the driver-specific documentation is meant to help
users of the media subsystem.

Move them to the admin-guide.

It should be noticed, however, that several of those files
are outdated and will require further work in order to make
them useful again.
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>

Since 2017, there is an space reserved for userspace API,
created by changeset 1d596dee ("docs: Create a user-space API guide").

As the media subsystem was one of the first subsystems to use
Sphinx, until this patch, we were keeping things on a separate
place.

Let's just use the new location, as having all uAPI altogether
will likely make things easier for developers.
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>

Using the field information attached to v4l2 buffers is not enough to
determine the type of field referenced by a DPB entry: the decoded
frame might contain the full picture (both top and bottom fields)
but the reference only point to one of them.
Let's add new V4L2_H264_DPB_ENTRY_FLAG_ flags to express that.

[Keep only 2 flags and add some details about they mean]
Signed-off-by: NJonas Karlman <jonas@kwiboo.se>
Signed-off-by: NBoris Brezillon <boris.brezillon@collabora.com>
Signed-off-by: NEzequiel Garcia <ezequiel@collabora.com>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>

Clarify that the expected order of scaling lists should follow the order
they are listed in the H264 standard.

The expected scaling list order,
for 4x4: Intra Y, Intra Cb, Intra Cr, Inter Y, Inter Cb, Inter Cr,
for 8x8: Intra Y, Inter Y, Intra Cb, Inter Cb, Intra Cr, Inter Cr.

Also clarify that the values in a scaling list should be in matrix order,
the same value order that vaapi, vdpau and nvdec use.
Signed-off-by: NJonas Karlman <jonas@kwiboo.se>
Reviewed-by: NPhilipp Zabel <p.zabel@pengutronix.de>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab@kernel.org>

This introduces the required definitions for HEVC decoding support with
stateless VPUs. The controls associated to the HEVC slice format provide
the required meta-data for decoding slices extracted from the bitstream.

They are not exported to the public V4L2 API since reworking this API
will likely be needed for covering various use-cases and new hardware.

Multi-slice decoding is exposed as a valid decoding mode to match current
H.264 support but it is not yet implemented.

The interface comes with the following limitations:
* No custom quantization matrices (scaling lists);
* Support for a single temporal layer only;
* No slice entry point offsets support;
* No conformance window support;
* No VUI parameters support;
* No support for SPS extensions: range, multilayer, 3d, scc, 4 bits;
* No support for PPS extensions: range, multilayer, 3d, scc, 4 bits.
Signed-off-by: NPaul Kocialkowski <paul.kocialkowski@bootlin.com>
[hverkuil-cisco@xs4all.nl: use 1ULL in flags defines in hevc-ctrls.h]
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

Since the uapi does not contain the num_ref_idx_active_override_flag,
drivers for decoders that do not parse slices themselves don't know
how to choose between the num_ref_idx_l[01]_default_active and the
num_ref_idx_l[01]_active override fields.

Instead, userspace must set the override fields to the default values
if the slice does not have the num_ref_idx_active_override flag set.
The drivers will then always enable the override internally and ignore
the default fields completely.

Clarify this requirement in the API documentation.
Signed-off-by: NPhilipp Zabel <p.zabel@pengutronix.de>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

Since dec_ref_pic_marking_bit_size is not a syntax element
itself, explicitly state that this is the size in bits of
the dec_ref_pic_marking() syntax element contained in the
slice.
Signed-off-by: NPhilipp Zabel <p.zabel@pengutronix.de>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

Those lists can be extracted from the dpb, let's simplify userspace
life and build that list kernel-side (generic helpers will be provided
for drivers that need this list).
Signed-off-by: NBoris Brezillon <boris.brezillon@collabora.com>
Reviewed-by: NNicolas Dufresne <nicolas.dufresne@collabora.com>
Reviewed-by: NEzequiel Garcia <ezequiel@collabora.com>
Reviewed-by: NPaul Kocialkowski <paul.kocialkowski@bootlin.com>
Tested-by: NPhilipp Zabel <p.zabel@pengutronix.de>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

Stateless decoders have different expectations about the
start code that is prepended on H264 slices. Add a
menu control to express the supported start code types
(including no start code).

Drivers are allowed to support only one start code type,
but they can support both too.

Note that this is independent of the H264 decoding mode,
which specifies the granularity of the decoding operations.
Either in frame-based or slice-based mode, this new control
will allow to define the start code expected on H264 slices.
Signed-off-by: NEzequiel Garcia <ezequiel@collabora.com>
Tested-by: NPhilipp Zabel <p.zabel@pengutronix.de>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

Some stateless decoders don't support per-slice decoding granularity
(or at least not in a way that would make them efficient or easy to use).

Expose a menu to control the supported decoding modes. Drivers are
allowed to support only one decoding but they can support both too.

To fully specify the decoding operation, we need to introduce
a start_byte_offset, to indicate where slices start.
Signed-off-by: NBoris Brezillon <boris.brezillon@collabora.com>
Reviewed-by: NPaul Kocialkowski <paul.kocialkowski@bootlin.com>
Tested-by: NPhilipp Zabel <p.zabel@pengutronix.de>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

Add the parsed VP8 frame pixel format and controls, to be used
with the new stateless decoder API for VP8 to provide parameters
for accelerator (aka stateless) codecs.
Reviewed-by: NTomasz Figa <tfiga@chromium.org>
Reviewed-by: NBoris Brezillon <boris.brezillon@collabora.com>
Reviewed-by: NNicolas Dufresne <nicolas.dufresne@collabora.com>
Signed-off-by: NPawel Osciak <posciak@chromium.org>
Signed-off-by: NEzequiel Garcia <ezequiel@collabora.com>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

Stateless video codecs will require both the H264 metadata and slices in
order to be able to decode frames.

This introduces the definitions for the structures used to pass the
metadata from the userspace to the kernel.

[hverkuil-cisco@xs4all.nl: add space after . in ".For"]
[hverkuil-cisco@xs4all.nl: sync v4l2_ctrl_h264_decode_params struct layout with header]
Co-developed-by: NMaxime Ripard <maxime.ripard@bootlin.com>
Reviewed-by: NPaul Kocialkowski <paul.kocialkowski@bootlin.com>
Reviewed-by: NTomasz Figa <tfiga@chromium.org>
Signed-off-by: NPawel Osciak <posciak@chromium.org>
Signed-off-by: NGuenter Roeck <groeck@chromium.org>
Signed-off-by: NMaxime Ripard <maxime.ripard@bootlin.com>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

Add MPEG-2 CID definitions for profiles and levels defined in ITU-T Rec.
H.262.
Signed-off-by: NPhilipp Zabel <p.zabel@pengutronix.de>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

Add following V4L2 QP parameters for H.264:
* V4L2_CID_MPEG_VIDEO_H264_I_FRAME_MIN_QP
* V4L2_CID_MPEG_VIDEO_H264_I_FRAME_MAX_QP
* V4L2_CID_MPEG_VIDEO_H264_P_FRAME_MIN_QP
* V4L2_CID_MPEG_VIDEO_H264_P_FRAME_MAX_QP

These controls will limit QP range for intra and inter frame,
provide more manual control to improve video encode quality.
Signed-off-by: NFish Lin <linfish@google.com>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

Avoid cell overlapping by changing some sizes, and changing the
font sizes when needed.

Tested with Sphinx 1.7.8.
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

add documentation to V4L2_CID_MPEG_VIDEO_FWHT_PARAMS
control and its related 'v4l2_ctrl_fwht_params' struct

[mchehab+samsung@kernel.org: remove extra blank lines]
Signed-off-by: NDafna Hirschfeld <dafna3@gmail.com>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

add documentation to V4L2_CID_FWHT_I/P_FRAME_QP
controls in ext-ctrls-codec.rst

[mchehab+samsung@kernel.org: remove extra blank lines]
Signed-off-by: NDafna Hirschfeld <dafna3@gmail.com>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

Use codespell to fix lots of typos over frontends.

Manually verified to avoid false-positives.
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: NPhilipp Zabel <p.zabel@pengutronix.de>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

The extended-controls.rst file had become too big. Split it up: each
control class reference gets its own rst file, and this file just
describes the Extended Control API.

Each control class reference is also moved up one level into the
table of contents to make it easier to find e.g. the codec control
reference.

Finally I rearranged the order so that all camera-related control
classes are grouped together, ditto for codec/jpeg and fm-rx/tx.

The ext-ctrls-codec.rst is still pretty big and it is a candidate
to split up further in the future, possibly per codec.
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

Allow to add fixed quantization parameter offset between luma and
chroma quantization parameters. This control directly corresponds
to the chroma_qp_index_offset field of the h.264 picture parameter
set.
Signed-off-by: NPhilipp Zabel <p.zabel@pengutronix.de>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

Allow to enable h.264 constrained intra prediction (macroblocks using
intra prediction modes are not allowed to use residual data and decoded
samples of neighboring macroblocks coded using inter prediction modes).
This control directly corresponds to the constrained_intra_pred_flag
field in the h.264 picture parameter set.
Signed-off-by: NPhilipp Zabel <p.zabel@pengutronix.de>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

The layout of the compound controls has changed to fix
32/64 bit alignment issues and the use of timestamps instead of
buffer indices to refer to buffers.
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

The venus and s5p-mfc drivers add the loop filter alpha/beta offset
controls V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_ALPHA/BETA with a range of
-6 to +6, inclusive. This is exactly the range specified for the slice
header fields slice_alpha_c0_offset_div2 and slice_beta_offset_div2,
which store half the actual filter offsets FilterOffsetA/B.

Clarify that this control contains the halved offsets.
Signed-off-by: NPhilipp Zabel <p.zabel@pengutronix.de>
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

Add a note mentioning that these two controls are not part of the
public API while they still stabilizing.
Signed-off-by: NHans Verkuil <hverkuil-cisco@xs4all.nl>
Reviewed-by: NPaul Kocialkowski <paul.kocialkowski@bootlin.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

All those files are under GFDL 1.1 or later, with no invariant sections.
Tag them as such.
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

This is not needed there. Also, the same UTF-8 encoding should
be used on all documents.
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

Whilst making an unrelated change to some Documentation, Linus sayeth:

  | Afaik, even in Britain, "whilst" is unusual and considered more
  | formal, and "while" is the common word.
  |
  | [...]
  |
  | Can we just admit that we work with computers, and we don't need to
  | use þe eald Englisc spelling of words that most of the world never
  | uses?

dictionary.com refers to the word as "Chiefly British", which is
probably an undesirable attribute for technical documentation.

Replace all occurrences under Documentation/ with "while".

Cc: David Howells <dhowells@redhat.com>
Cc: Liam Girdwood <lgirdwood@gmail.com>
Cc: Chris Wilson <chris@chris-wilson.co.uk>
Cc: Michael Halcrow <mhalcrow@google.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Reported-by: NLinus Torvalds <torvalds@linux-foundation.org>
Signed-off-by: NWill Deacon <will.deacon@arm.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Stateless video decoding engines require both the MPEG-2 slices and
associated metadata from the video stream in order to decode frames.

This introduces definitions for a new pixel format, describing buffers
with MPEG-2 slice data, as well as control structure sfor passing the
frame metadata to drivers.

This is based on work from both Florent Revest and Hugues Fruchet.
Signed-off-by: NPaul Kocialkowski <paul.kocialkowski@bootlin.com>
Signed-off-by: NMaxime Ripard <maxime.ripard@bootlin.com>
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

Add a new control V4L2_CID_MPEG_VIDEO_VP9_PROFILE for VP9 profiles. This control
allows selecting the desired profile for VP9 encoder and querying for supported
profiles by VP9 encoder/decoder.

Though this control is similar to V4L2_CID_MPEG_VIDEO_VP8_PROFILE, we need to
separate this control from it because supported profiles usually differ between
VP8 and VP9.
Signed-off-by: NKeiichi Watanabe <keiichiw@chromium.org>
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

Add a menu control V4L2_CID_MPEG_VIDEO_VP8_PROFILE for VP8 profile and make
V4L2_CID_MPEG_VIDEO_VPX_PROFILE an alias of it. This new control is used to
select the desired profile for VP8 encoder and query for supported profiles by
VP8 encoder/decoder.

Though we have originally a control V4L2_CID_MPEG_VIDEO_VPX_PROFILE and its name
contains 'VPX', it works only for VP8 because supported profiles usually differ
between VP8 and VP9. In addition, this control cannot be used for querying since
it is not a menu control but an integer control, which cannot return an
arbitrary set of supported profiles.

The new control V4L2_CID_MPEG_VIDEO_VP8_PROFILE is a menu control as with
controls for other codec profiles. (e.g. H264)

In addition, this patch also fixes the use of V4L2_CID_MPEG_VIDEO_VPX_PROFILE in
drivers of Qualcomm's venus and Samsung's s5p-mfc.
Signed-off-by: NKeiichi Watanabe <keiichiw@chromium.org>
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>

V4L2_CID_DV_RX_POWER_PRESENT refers to a receiver, not a transmitter.
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>