[VDPAU] [PATCH] vdpau.h: define a more strict ABI policy

[Christian König]

Am 05.12.2014 um 23:56 schrieb Aaron Plattner:
> Because structures defined in vdpau.h may be used outside of the libvdpau
> interface itself, it's important for them to not change, even to add new fields
> to the end.  Clarify this by tightening the restriction on how structures can be
> modified.
>
> This means that we can also *relax* the restriction on versioned structures that
> says that they can only be extended by adding fields to the end.  As long as
> uint32_t struct_version is the first field of the structure, the implementation
> can look at that to determine the complete layout of the rest of the fields.
>
> Signed-off-by: Aaron Plattner <aplattner at nvidia.com>

Sounds like a very valid update on how to extend the interface to me.

Patch is Reviewed-by: Christian König <christian.koenig at amd.com>

> ---
> There was some discussion recently about whether or not it's acceptable to
> extend existing structures by adding fields to the end.  There was some debate
> within NVIDIA about this and the conclusion we reached was that the size of each
> structure should be included as part of the ABI.  This change attempts to
> describe that and provide guidelines about how existing structures should be
> extended.
>
>   include/vdpau/vdpau.h | 23 +++++++++++++++++++----
>   1 file changed, 19 insertions(+), 4 deletions(-)
>
> diff --git a/include/vdpau/vdpau.h b/include/vdpau/vdpau.h
> index 4444de35b876..41bdf2d75325 100644
> --- a/include/vdpau/vdpau.h
> +++ b/include/vdpau/vdpau.h
> @@ -707,10 +707,25 @@
>    *
>    * A few structures are considered plausible candidates for future extension.
>    * Such structures include a version number as the first field, indicating the
> - * exact layout of the client-provided data. Such structures may only be
> - * modified by adding new fields to the end of the structure, so that the
> - * original structure definition is completely compatible with a leading
> - * subset of fields of the extended structure.
> + * exact layout of the client-provided data. When changing such structures, the
> + * old structure must be preserved and a new structure created. This allows
> + * applications built against the old version of the structure to continue to
> + * interoperate. For example, to extend the VdpProcamp structure, define a new
> + * VdpProcamp1 and update VdpGenerateCSCMatrix to take the new structure as an
> + * argument. Document in a comment that the caller must fill the struct_version
> + * field with the value 1. VDPAU implementations should use the struct_version
> + * field to determine which version of the structure the application was built
> + * against.  Note that you cannot simply increment the value of
> + * VDP_PROCAMP_VERSION because applications recompiled against a newer version
> + * of vdpau.h but that have not been updated to use the new structure must still
> + * report that they're using version 0.
> + *
> + * Note that the layouts of VdpPictureInfo structures are defined by their
> + * corresponding VdpDecoderProfile numbers, so no struct_version field is
> + * needed for them. This layout includes the size of the structure, so new
> + * profiles that extend existing functionality may incorporate the old
> + * VdpPictureInfo as a substructure, but may not modify existing VdpPictureInfo
> + * structures.
>    *
>    * \subsection extend_functions Functions
>    *