[PATCH weston v6 04/12] compositor: Version the backend configuration structures

[Bryce Harrington]

With this struct versioning, it is possible to add new options without
breaking the ABI, as long as all additions are made to the end of a
struct and nothing existing is modified or removed.  When things are
added, the structure's size will increase, and we'll use this size as
our minor version number.  If existing things need to be changed, then
the major version, struct_version, is incremented to indicate the ABI
break.

>From our call sites in main these major and minor version will be
recorded as struct_version and struct_size.  Each backend will then
verify these against its own assumptions.  So long as the backend's
struct is equal or larger than what was passed in and the major versions
are equal, we're good; but if it is larger, then this is a fatal error.

Signed-off-by: Bryce Harrington <bryce at osg.samsung.com>
Reviewed-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>

v6:
 - Document refs for alternatives/assumptions for backend configs
v5:
 - Move the header changes to a pre-requisite patch from the drm backend

Signed-off-by: Bryce Harrington <bryce at osg.samsung.com>
---
 src/compositor.h | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/src/compositor.h b/src/compositor.h
index 5ca497c..a329dbe 100644
--- a/src/compositor.h
+++ b/src/compositor.h
@@ -684,8 +684,30 @@ struct weston_backend_output_config {
  * passed to the backend's init entry point. The backend will
  * likely want to subclass this in order to handle backend specific
  * data.
+ *
+ * NOTE: Alternate designs were proposed (Feb 2016) for using opaque
+ * structures and for section+key/value getter/setters.  The rationale
+ * for selecting the transparent structure design is based on several
+ * assumptions which may require re-evaluating the design choice if they
+ * fail to hold.
  */
 struct weston_backend_config {
+   /** Major version for the backend-specific config struct
+    *
+    * This version must match exactly what the backend expects, otherwise
+    * the struct is incompatible.
+    */
+   uint32_t struct_version;
+
+   /** Minor version of the backend-specific config struct
+    *
+    * This must be set to sizeof(struct backend-specific config).
+    * If the value here is smaller than what the backend expects, the
+    * extra config members will assume their default values.
+    *
+    * A value greater than what the backend expects is incompatible.
+    */
+   size_t struct_size;
 };
 
 struct weston_backend {
-- 
1.9.1