Re: [RFC 7/7] media: uapi: make H264 stateless codec interface public

[Ezequiel Garcia <ezequiel@collabora.com>]

On Thu, 2020-06-25 at 09:52 +0200, Hans Verkuil wrote:
> On 23/06/2020 20:28, Ezequiel Garcia wrote:
> > The H264 interface is now ready to be part of the official
> > public API.
> > 
> > In addition, sanitize header includes.
> > 
> > Signed-off-by: Ezequiel Garcia <ezequiel@collabora.com>
> > ---
> >  drivers/staging/media/hantro/hantro_hw.h                  | 5 ++---
> >  include/media/v4l2-ctrls.h                                | 3 ++-
> >  include/media/v4l2-h264.h                                 | 2 +-
> >  .../{media/h264-ctrls.h => uapi/linux/v4l2-h264-ctrls.h}  | 8 ++------
> >  4 files changed, 7 insertions(+), 11 deletions(-)
> >  rename include/{media/h264-ctrls.h => uapi/linux/v4l2-h264-ctrls.h} (96%)
> 
> This isn't quite how this should be done.
> 
> The V4L2_PIX_FMT_H264_SLICE define and the V4L2_CTRL_TYPE_H264_* defines should
> move to videodev2.h.
> 

OK.

> The remaining CID defines and the data structures should be moved to v4l2-controls.h.
> 

OK.

> Yes, I know, v4l2-controls.h is getting large. At some point (could actually be
> done in a follow-up patch) the codec controls in v4l2-controls.h should be split off
> into their own header (v4l2-codec-controls.h).
> 

OK, that makes sense.

> One more thing that I was wondering about:
> 
> #define V4L2_CID_MPEG_VIDEO_H264_SPS            (V4L2_CID_MPEG_BASE+1000)
> 
> These controls are at V4L2_CID_MPEG_BASE+1000. But I was wondering if:
> 
> 1) wouldn't it be a good thing to use new CID values since this is the actual
>    uAPI version? This series changes the layout of several structs, so creating
>    new CID values to prevent confusion in applications might be a good idea.
> 
> 2) related to 1): should we make a new control class for stateless codecs?
>    Currently it is mixed in with the stateful codec controls, but I am not so
>    sure that that is such a good idea. Creating a separate stateless codec
>    control class would be a clean separation of stateful and stateless, and it
>    would probably improve the documentation as well.
> 

Good idea.

>    The only 'standard' codec control that is used by stateless codecs is
>    V4L2_CID_MPEG_VIDEO_H264_PROFILE in hantro, although it is not clear to me
>    how it is used. It looks like it is just to report the supported profiles?
>    But it isn't present in the cedrus driver, so it's a bit odd.
> 

I can take a look and add profiles to cedrus as well.

> Thank you for working on finalizing the H264 API.
> 

Thanks for the guidelines and feedback.

I will drop this patch for now, since I think we
now have a clear guideline on how to go public
(which was the goal of this RFC!).

I will move forward the H264 uAPI changes,
and then we can try to push H264, MPEG-2 and VP8
public, as these interfaces are the ones
that seem stable.

Thanks!
Ezequiel  

> Regards,
> 
> 	Hans
> 
> > diff --git a/drivers/staging/media/hantro/hantro_hw.h b/drivers/staging/media/hantro/hantro_hw.h
> > index 4053d8710e04..48d5be144319 100644
> > --- a/drivers/staging/media/hantro/hantro_hw.h
> > +++ b/drivers/staging/media/hantro/hantro_hw.h
> > @@ -11,9 +11,8 @@
> >  
> >  #include <linux/interrupt.h>
> >  #include <linux/v4l2-controls.h>
> > -#include <media/h264-ctrls.h>
> > -#include <media/mpeg2-ctrls.h>
> > -#include <media/vp8-ctrls.h>
> > +
> > +#include <media/v4l2-ctrls.h>
> >  #include <media/videobuf2-core.h>
> >  
> >  #define DEC_8190_ALIGN_MASK	0x07U
> > diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h
> > index f40e2cbb21d3..fc725ba2ebd8 100644
> > --- a/include/media/v4l2-ctrls.h
> > +++ b/include/media/v4l2-ctrls.h
> > @@ -13,13 +13,14 @@
> >  #include <linux/videodev2.h>
> >  #include <media/media-request.h>
> >  
> > +#include <linux/v4l2-h264-ctrls.h>
> > +
> >  /*
> >   * Include the stateless codec compound control definitions.
> >   * This will move to the public headers once this API is fully stable.
> >   */
> >  #include <media/mpeg2-ctrls.h>
> >  #include <media/fwht-ctrls.h>
> > -#include <media/h264-ctrls.h>
> >  #include <media/vp8-ctrls.h>
> >  #include <media/hevc-ctrls.h>
> >  
> > diff --git a/include/media/v4l2-h264.h b/include/media/v4l2-h264.h
> > index f08ba181263d..d2314f4d4490 100644
> > --- a/include/media/v4l2-h264.h
> > +++ b/include/media/v4l2-h264.h
> > @@ -10,7 +10,7 @@
> >  #ifndef _MEDIA_V4L2_H264_H
> >  #define _MEDIA_V4L2_H264_H
> >  
> > -#include <media/h264-ctrls.h>
> > +#include <media/v4l2-ctrls.h>
> >  
> >  /**
> >   * struct v4l2_h264_reflist_builder - Reference list builder object
> > diff --git a/include/media/h264-ctrls.h b/include/uapi/linux/v4l2-h264-ctrls.h
> > similarity index 96%
> > rename from include/media/h264-ctrls.h
> > rename to include/uapi/linux/v4l2-h264-ctrls.h
> > index 6446ec9f283d..a06f60670d68 100644
> > --- a/include/media/h264-ctrls.h
> > +++ b/include/uapi/linux/v4l2-h264-ctrls.h
> > @@ -2,14 +2,10 @@
> >  /*
> >   * These are the H.264 state controls for use with stateless H.264
> >   * codec drivers.
> > - *
> > - * It turns out that these structs are not stable yet and will undergo
> > - * more changes. So keep them private until they are stable and ready to
> > - * become part of the official public API.
> >   */
> >  
> > -#ifndef _H264_CTRLS_H_
> > -#define _H264_CTRLS_H_
> > +#ifndef __LINUX_V4L2_H264_CONTROLS_H
> > +#define __LINUX_V4L2_H264_CONTROLS_H
> >  
> >  #include <linux/videodev2.h>
> >  
> >