Re: [PATCH v3 1/2] media: v4l: Add definitions for the HEVC slice format and controls

From: Paul Kocialkowski
Date: Fri Apr 19 2019 - 14:59:58 EST


Hi,

On Tue, 2019-04-02 at 13:51 +0200, Hans Verkuil wrote:
> On 2/14/19 10:53 AM, Paul Kocialkowski wrote:

[...]

> > +.. c:type:: v4l2_hevc_dpb_entry
> > +
> > +.. cssclass:: longtable
> > +
> > +.. flat-table:: struct v4l2_hevc_dpb_entry
> > + :header-rows: 0
> > + :stub-columns: 0
> > + :widths: 1 1 2
> > +
> > + * - __u32
> > + - ``buffer_tag``
> > + - The V4L2 buffer tag that matches the associated reference picture.
>
> This struct documentation is out of date with the actual struct!

Woops, sorry about that. I'll make another pass on the structures vs
docs before submitting the next version.

> > +#define V4L2_HEVC_DPB_ENTRY_RPS_ST_CURR_BEFORE 0x01
> > +#define V4L2_HEVC_DPB_ENTRY_RPS_ST_CURR_AFTER 0x02
> > +#define V4L2_HEVC_DPB_ENTRY_RPS_LT_CURR 0x03
> > +
> > +#define V4L2_HEVC_DPB_ENTRIES_NUM_MAX 16
> > +
> > +struct v4l2_hevc_dpb_entry {
> > + __u64 timestamp;
>
> I would call this 'reference_ts' rather than plain 'timestamp'.
> Or at least some other name that reflects what the timestamp
> refers to.

Well, I think using "ts" instead of "timestamp" is much less explicit
(I'm really not a big fan of abbreviations...).

Also, this field is in the dpb entry structure and since a dpb entry
describes a reference, I find it quite straightforward already without
any added prefix. The prefix feels redundant with the name of the
structure that holds the element.

I think the same should apply for mpeg-2 and h.264.

> > + __u8 rps;
> > + __u8 field_pic;
> > + __u16 pic_order_cnt[2];
> > + __u8 padding[2];
>
> padding fields here or elsewhere are not documented. Do you really
> need them? What if you changed rps and field_pic to __u16 instead?
>
> Padding fields are painful to maintain in my experience.

I think we'll need to rework the controls to include flags and such in
the not-too-distant future. So there will be an occasion to change it
then (the same work also needs to be done for MPEG-2).

If you prefer that we make the change now and later update it along
with the controls, I can definitely do that too.

Cheers,

Paul

--
Paul Kocialkowski, Bootlin
Embedded Linux and kernel engineering
https://bootlin.com