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

[Gwenole Beauchesne]

Hi,

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(-)