[PATCH 5/5] compositor: Document refs for alternatives/assumptions for backend configs

[Bryce Harrington]

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

diff --git a/src/main.c b/src/main.c
index 7370292..310382a 100644
--- a/src/main.c
+++ b/src/main.c
@@ -748,6 +748,19 @@ load_drm_backend(struct weston_compositor *c, const char *backend,
 					 "gbm-format", &config->base.format,
 					 NULL);
 
+	/* Use a major/minor versioning scheme to enable backends to detect
+	 * ABI changes in the config struct we're passing in.
+	 *
+	 * NOTE: Alternate designs were proposed 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
+	 */
 	config->base.base.struct_version = 1;
 	config->base.base.struct_size = sizeof(struct weston_drm_backend_config);
 	config->base.configure_output = drm_configure_output;
-- 
1.9.1