From 20b66c3004bf47ed56c1b2fc2fb4503d3fd60351 Mon Sep 17 00:00:00 2001 From: Bryce Harrington Date: Fri, 15 Apr 2016 20:28:29 -0700 Subject: [PATCH] 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 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 [Pekka: bring back the archive links Bryce looked up.] Signed-off-by: Pekka Paalanen --- src/compositor.h | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) 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 {