compositor: Version the backend configuration structures

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@osg.samsung.com>

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@osg.samsung.com>
[Pekka: bring back the archive links Bryce looked up.]
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>

1 files changed, 26 insertions, 0 deletions

diff --git a/src/compositor.h b/src/compositor.h
index 5ca497c7..cb9df007 100644
--- a/src/compositor.h
+++ b/src/compositor.h
@@ -684,8 +684,34 @@ 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[1] and for section+key/value getter/setters[2].  The rationale
+ * for selecting the transparent structure design is based on several
+ * assumptions[3] which may require re-evaluating the design choice if they
+ * fail to hold.
+ *
+ * 1: https://lists.freedesktop.org/archives/wayland-devel/2016-February/026989.html
+ * 2: https://lists.freedesktop.org/archives/wayland-devel/2016-February/026929.html
+ * 3: https://lists.freedesktop.org/archives/wayland-devel/2016-February/027228.html
  */
 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 {