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(-) _______________________________________________ Libva mailing list Libva@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/libva
