Work out new ABI for test harness
Status
- Status: Under Review
- Version: 2024-04-04.0
Description
The way-assay protocol is a mechanism by which the test client (ie. way-assay) may connect and interact with an instrumented Wayland compositor. While it is possible to have multiple implementations of the test harness, the protocol is designed to be focused on supporting way-assay's test harness and set of tests.
The way-assay test harness will dlopen the attachment ABI shared object. The attachment ABI will provide an interface to unlock all functionality made available for test.
Features
Each unit in the set of all functionality exposed by the test protocols is known as a feature. No features are required to be implemented by a compostior, however this would result in few available test cases to be run.
Features are designed to allow compositor specific behavior to be recognized and testable.
example: Tiling window managers may expose certain window positioning directives via a tiled feature set.
Versioning
tl;dr: A compositor should implement a single version of a feature protocol.
It is anticipated that there will be a single implementation of the client (test harness and tests), ie. way-assay will be the only user considered when designing this protocol. Therefore, falling back to older versions is something only the client (way-assay) is expected to need to do. The server may implement older, or newer versions of the feature. With this comes the caveat that protocols versions may only be changed when way-assay is ready to handle them.
example: Weston implements core protocols v2. Weston would not need to also expose v1 of the protocol.
example: NoWay implements core protocols v1. way-assay may or may not attempt to run tests even though it is not the newest version of the core feature protocol.
Deprecation
tl;dr: A compositor cannot rely on deprecated protocols to be tested.
Protocols may be deprecated. The implication is a Wayland compositor that advertises such version of protocol will not be tested by the latest version of way-assay.
example: NoWay implements spiffy feature v1, but not v2. v1 is deprecated. way-assay will not run any test relying on the spiffy feature.
Attachment ABI
This is the main entry point for interfacing with the test Wayland server. It serves simply to get a handle to the real functionality while limiting version churn. It shall be dlopen'd by the way-assay test suite.
Symbol | Description |
---|---|
v (v == 1) | Global with the latest version of this structure. |
list | List features supported by this Wayland compositor. |
attach | Attaches to the test harness feature. Returns an instance of the test harness in accordance to the specified version If the feature requires resources that need to be freed, it shall provide its own detach function. |
#define WAY_ASSAY_ABI_VERSION 1;
#define WAY_ASSAY_FEATURE_CORE_V1 "core_v1"
#define WAY_ASSAY_FEATURE_STACKING_V1 "stacking_v1"
struct __attribute__((packed)) assay_attachment {
uint32_t v;
const char *(*list)();
void *(*attach)(const char *function);
};
/// Connection to test harness
#[repr(C)]
struct AssayAttachment {
version: u32,
list: unsafe extern "C" fn() -> *const i8,
attach: unsafe extern "C" fn(feature: *const i8) -> *mut c_void,
}
Core Feature
The core feature is an interface which should be implemented by all compositors. It provides the ability to start and connect to the Wayland server being tested.
These are the primary interfaces for interacting with the test Wayland server. Unlike the attachment protocol, this table is dependent upon the version advertised from the attachment ABI.
Optional | Name | Description |
---|---|---|
n | start | starts the test wayland server |
n | stop | stops the test wayland server |
n | create_client | creates a connection to the wayland server and returns a handle |
y | output_pos | obtains the starting coordinate of the output in the global coordinate space. |
struct way_assay_client;
// Position in the global coordinate space.
struct position {
int x, y, z
};
struct __attribute__((packed)) way_assay_core_v1 {
void (*start)();
void (*stop)();
struct way_assay_client *(*create_client)();
struct position (*output_pos)(struct way_assay_client *client,
struct wl_output *output);
};
struct Position {
x: i32,
y: i32,
z: i32,
}
#[repr(C)]
struct AssayClient {
}
#[repr(C)]
struct AssayCoreV1 {
start: unsafe extern "C" fn(),
stop: unsafe extern "C" fn(),
create_client: unsafe extern "C" fn() -> *mut AssayClient,
output_pos: unsafe extern "C" fn(client: *mut AssayClient,
output: *mut wl_proxy) -> Position,
}
Stacking Feature
struct way_assay_client;
struct __attribute__((packed)) way_assay_stacking_v1 {
void (*place_at)(struct way_assay_client *client, struct wl_display *display,
struct wl_surface *surface, struct position pos);
void (*activate)(struct wl_surface *surface);
};
#[repr(C)]
struct AssayStackingV1 {
place_at: unsafe extern "C" fn(client: *mut AssayClient, display: *mut wl_display, surface: *mut wl_proxy, pos: Position),
activate: unsafe extern "C" fn(client: *mut AssayClient, surface: *mut wl_proxy),
}