From a58bcd7481db4b20533b2b3667df6c45e7ad7225 Mon Sep 17 00:00:00 2001
From: Isaac Freund <mail@isaacfreund.com>
Date: Tue, 24 Feb 2026 12:43:43 +0100
Subject: [PATCH] doc: add frozen=true interface attribute

This is useful for scanners that use knowledge of the object creation
hierarchy such as zig-wayland [1]. Currently zig-wayland uses a
hardcoded list of frozen interfaces.

[1]: https://codeberg.org/ifreund/zig-wayland

Signed-off-by: Isaac Freund <mail@isaacfreund.com>
---
 doc/book/src/Message_XML.md | 12 +++++++++++-
 protocol/wayland.dtd        |  1 +
 protocol/wayland.xml        |  4 ++--
 3 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/doc/book/src/Message_XML.md b/doc/book/src/Message_XML.md
index c44deee9..2a3c5f3f 100644
--- a/doc/book/src/Message_XML.md
+++ b/doc/book/src/Message_XML.md
@@ -140,7 +140,8 @@ usage of the interface.
     the interfaces part of the same interface ancestry tree. The exception to
     this rule are interfaces which are forever stuck to version 1, which is
     usually caused by having multiple parent interfaces with independent
-    ancestor global interfaces.
+    ancestor global interfaces. In this case, the `frozen="true"` attribute
+    described below should be used.
 
     A protocol object may have any defined version of the interface. The version
     of the object is determined at runtime either by inheritance from another
@@ -152,6 +153,15 @@ usage of the interface.
     thoroughly updated as required. In such cases the object shall function as
     with the highest defined interface version.
 
+**Optional attributes**
+
+`frozen`="`true`"
+  : The interface is frozen and forever stuck at version 1.
+
+    This attribute should be applied to interfaces that have multiple parent
+    interfaces with independent ancestor global interfaces, for example
+    `wl_buffer` and `wl_callback`.
+
 ### request
 
 Parent elements: interface
diff --git a/protocol/wayland.dtd b/protocol/wayland.dtd
index b97372c5..ae8340d6 100644
--- a/protocol/wayland.dtd
+++ b/protocol/wayland.dtd
@@ -4,6 +4,7 @@
 <!ELEMENT interface (description?,(request|event|enum)+)>
   <!ATTLIST interface name CDATA #REQUIRED>
   <!ATTLIST interface version CDATA #REQUIRED>
+  <!ATTLIST interface frozen CDATA #IMPLIED>
 <!ELEMENT request (description?,arg*)>
   <!ATTLIST request name CDATA #REQUIRED>
   <!ATTLIST request type CDATA #IMPLIED>
diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 19f18479..513b8fd8 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -173,7 +173,7 @@
     </event>
   </interface>
 
-  <interface name="wl_callback" version="1">
+  <interface name="wl_callback" version="1" frozen="true">
     <description summary="callback object">
       Clients can handle the 'done' event to get notified when
       the related request is done.
@@ -503,7 +503,7 @@
     </request>
   </interface>
 
-  <interface name="wl_buffer" version="1">
+  <interface name="wl_buffer" version="1" frozen="true">
     <description summary="content for a wl_surface">
       A buffer provides the content for a wl_surface. Buffers are
       created through factory interfaces such as wl_shm, wp_linux_buffer_params