[Libva] [PATCH 0/3] Fix versioning (VA-API, libva, package name)

[Gwenole Beauchesne]

Hi,

I will push the next patch series in the coming days, along with
auto-generated Debian packaging rules, and then I am done with 1.0.15.
The current implementation does not cause any regression. VA
compatibility will be written if the API needs to be upgraded.

Regards,
Gwenole.

> Here is a series of patches that addresses versioning issues in
> VA-API, the library (DSO) name, and the library name as shipped.
>
> * Requirements
>
> We don't want to change the SONAME to preserve compatibility with
> applications that dlopen() libva.so.1. Thus any new libva version
> shall be binary compatible with prior versions.
>
> This means:
> - No binary incompatible change shall occur
> - Any new data structure field will be appended at the end of the structure
> - Any new bit-field shall be inserted at appropriate location to
>  maintain LSB order (as no known libva runs on MSB platforms at this
>  time)
> - If a data structure is changed, we shall still support the older one
> - No function is removed
> - If a function is modified, a compatibility version one is provided
> - We use versioned symbols
>
> * VA-API versioning
> - Increment major version for any ABI change (which shall not occur!)
> - Increment minor version for any interface change (new function, change)
> - Increment micro version for any change (new flag, new codec definition)
> - reset micro version to zero when minor version is incremented
> - reset minor version to zero when major version is incremented
>
> * libva package versioning
> - Increment major version when API major version changes (generated)
> - Increment minor version when API minor version changes (generated)
> - Increment micro version for any new release
> - increment micro for any library release
> - reset micro version to zero when VA-API major or minor version is incremented
>
> * DSO versioning
> - The SONAME shall remain to libva.so.1 for VA-API 0.x.y
> - The library name is generated as libva.<x>.<y>.0 where
>  <x> = VA-API major version + 1
>  <y> = 100 * VA-API minor version + VA-API micro version
>
> For example:
> VA-API 0.32.0 generates libva.so.1.3200.0 (libva 1.0.14 as of today)
> VA-API 0.34.1 generates libva.so.1.3401.0 (e.g. libva 1.2.1)
> VA-API 1.2.13 generates libva.so.2.213.0  (e.g. libva 2.2.13)
>
> * Symbol versioning
> Symbol versioning will be used to maintain backwards compatibility for
> new functions we introduce or functions where we change the arguments.
>
> Use-case: change vaInitialize() function to take an extra argument for
> returning the VA-API micro version. Thus, we will have vaInitialize()
> that represents the old 0.32.0 version with 3 arguments, and a new
> version for e.g. 0.32.1 with 4 arguments. Symbols in DSO will be
> vaInitialize and vaInitialize@@VA_API_0.32.1.
>
> Through clever macros, we can also provide source compatibility with 3
> args or 4 args variants of vaInitialize(). i.e. user code can still
> use plain vaInitialize() function name.
>
> 1. New exported interface in <va/va.h> will always appear as the
> latest one, thus the 4-argument vaInitialize().
>
> 2. <va/va_compat.h> will include the magic to
> - redirect the 3-arg vaInitialize() to the older one (vaInitialize)
> - redirect the 4-arg vaInitialize() to the new one (vaInitialize@@VA_API_0.32.1)
> - alias implementations to plain vaInitialize() [.symver feature]
>
> 3. va_compat.c will implement the older API function in terms of the
> new one. If function that is modified is a VA hook (in the VTable),
> the older hook is still maintained but a new one with an appropriate
> suffix (2, 3, 4, etc.) is appended to the end of the VTable. On the
> drivers side, we will extend the initialization routine to match
> VA-API versions too.
>
> Gwenole Beauchesne (3):
>  API: fix versioning.
>  libva: fix reported version as the one from VA-API.
>  vainfo: report both VA-API and libva versions.
>
>  configure.ac            |   67 ++++++++++++++++++++++++++++++++++++++--------
>  test/vainfo/Makefile.am |    7 +++-
>  test/vainfo/vainfo.c    |    3 +-
>  va/va.c                 |    2 +-
>  va/va_version.h.in      |   28 ++++++++++----------
>  5 files changed, 77 insertions(+), 30 deletions(-)
>
>