Present: add PresentPixmapSynced

Adds an augmented version of PresentPixmap supporting explicit
synchronization with a direct rendering device. This takes the form of
timeline DRM synchronization objects, along with acquire and release
points on those timelines. Implementations advertising
PresentCapabilitySyncobj will wait for the acquire point to be signaled
before executing the PresentPixmap request, and signal the release point
after any GPU operations on the pixmap have completed.

Signed-off-by: Erik Kurzinger <ekurzinger@nvidia.com>

4 files changed, 146 insertions, 6 deletions

diff --git a/include/X11/extensions/presentproto.h b/include/X11/extensions/presentproto.h
index d8dc6d2..ea80863 100644
--- a/include/X11/extensions/presentproto.h
+++ b/include/X11/extensions/presentproto.h
@@ -24,6 +24,7 @@
 #define _PRESENT_PROTO_H_
 
 #include <X11/extensions/presenttokens.h>
+#include <X11/extensions/dri3proto.h>
 
 #define Window CARD32
 #define Pixmap CARD32
@@ -136,6 +137,37 @@ typedef struct {
 } xPresentQueryCapabilitiesReply;
 #define sz_xPresentQueryCapabilitiesReply       32
 
+typedef struct {
+    CARD8   reqType;
+    CARD8   presentReqType;
+    CARD16  length;
+    Window  window;
+
+    Pixmap  pixmap;
+    CARD32  serial;
+
+    Region  valid;
+    Region  update;
+
+    INT16   x_off;
+    INT16   y_off;
+    CARD32  target_crtc;
+
+    DRI3Syncobj acquire_syncobj;
+    DRI3Syncobj release_syncobj;
+    CARD64 acquire_point;
+    CARD64 release_point;
+
+    CARD32  options;
+    CARD32  pad1;
+
+    CARD64  target_msc;
+    CARD64  divisor;
+    CARD64  remainder;
+    /* followed by a LISTofPRESENTNOTIFY */
+} xPresentPixmapSyncedReq;
+#define sz_xPresentPixmapSyncedReq	88
+
 /*
  * Events
  *
diff --git a/include/X11/extensions/presenttokens.h b/include/X11/extensions/presenttokens.h
index 400e84d..8004625 100644
--- a/include/X11/extensions/presenttokens.h
+++ b/include/X11/extensions/presenttokens.h
@@ -25,7 +25,7 @@
 
 #define PRESENT_NAME			"Present"
 #define PRESENT_MAJOR			1
-#define PRESENT_MINOR			3
+#define PRESENT_MINOR			4
 
 #define PresentNumberErrors		0
 #define PresentNumberEvents		0
@@ -36,8 +36,9 @@
 #define X_PresentNotifyMSC		2
 #define X_PresentSelectInput		3
 #define X_PresentQueryCapabilities      4
+#define X_PresentPixmapSynced		5
 
-#define PresentNumberRequests		5
+#define PresentNumberRequests		6
 
 /* Present operation options */
 #define PresentOptionNone               0
@@ -62,11 +63,13 @@
 #define PresentCapabilityFence          2
 #define PresentCapabilityUST            4
 #define PresentCapabilityAsyncMayTear   8
+#define PresentCapabilitySyncobj        16
 
 #define PresentAllCapabilities  (PresentCapabilityAsync | \
                                  PresentCapabilityFence | \
                                  PresentCapabilityUST | \
-                                 PresentCapabilityAsyncMayTear)
+                                 PresentCapabilityAsyncMayTear | \
+                                 PresentCapabilitySyncobj)
 
 #define PresentAllAsyncCapabilities (PresentCapabilityAsync | PresentCapabilityAsyncMayTear)
 
diff --git a/presentproto.pc.in b/presentproto.pc.in
index 829d608..f5d5b8b 100644
--- a/presentproto.pc.in
+++ b/presentproto.pc.in
@@ -3,5 +3,5 @@ includedir=@includedir@
  
 Name: PresentProto
 Description: Present extension headers
-Version: 1.3
+Version: 1.4
 Cflags: -I${includedir}
diff --git a/presentproto.txt b/presentproto.txt
index b474093..56c20d4 100644
--- a/presentproto.txt
+++ b/presentproto.txt
@@ -1,5 +1,5 @@
 			The Present Extension
-			     Version 1.3
+			     Version 1.4
 			      2023-06-13
       
 			    Keith Packard
@@ -63,7 +63,8 @@ PRESENTOPTION { PresentOptionAsync,
 PRESENTCAPABILITY { PresentCapabilityAsync,
 		    PresentCapabilityFence,
 		    PresentCapabilityUST,
-		    PresentCapabilityAsyncMayTear }
+		    PresentCapabilityAsyncMayTear,
+		    PresentCapabilitySyncobj }
 
 PRESENTCOMPLETEKIND { PresentCompleteKindPixmap,
 		      PresentCompleteKindMSCNotify }
@@ -359,6 +360,85 @@ The name of this extension is "Present"
 	defined by the extension, but is expected to be on the order
 	of milliseconds or less.
 
+	PresentCapabilitySyncobj means that the target device supports
+	explicit synchronization using timeline DRM synchronization
+	objects. See the PresentPixmapSynced request for details.
+
+┌───
+    PresentPixmapSynced
+	window: WINDOW
+	pixmap: PIXMAP
+	serial: CARD32
+	valid-area: REGION or None
+	update-area: REGION or None
+	x-off, y-off: INT16
+	target-crtc: CRTC or None
+	acquire-syncobj: SYNCOBJ or None
+	release-syncobj: SYNCOBJ or None
+	acquire-point: CARD64
+	release-point: CARD64
+	options: SETofPRESENTOPTION
+	target-msc: CARD64
+	divisor: CARD64
+	remainder: CARD64
+	notifies: LISTofPRESENTNOTIFY
+└───
+	Errors: Window, Pixmap, Match, Value
+
+	Identical to the PresentPixmap request, except that instead of the
+	'wait-fence' and 'idle-fence' arguments it accepts mandatory
+	'acquire-syncobj' and 'release-syncobj' arguments, along with
+	corresponding acquire and release points, to be used for explicit
+	timeline-based GPU synchronization. The 'acquire-point' and
+	'release-point' are assumed to correspond to timeline points on the
+	respective DRM syncobjs.
+
+	The contents of the Pixmap will not be accessed by the server until the
+	'acquire-point' on the acquire timeline has been signaled by the
+	client. The fence need not be submitted at the time the
+	PresentPixmapSynced request is issued.
+
+	Once the 'release-point' on the release timeline has been signaled, the
+	client may assume that no further GPU or CPU access to the Pixmap by
+	the server will occur as part of the originating PresentPixmapSynced
+	request.  Note that this is a stronger guarantee than what is provided
+	by the 'idle-fence' argument of the PresentPixmap request or the
+	delivery of a PresentIdleNotify event, as those do not necessarily
+	imply that the Pixmap is idle on the GPU.
+
+	The server may wait for the acquire point and signal the release point
+	itself, as will typically happen if the request is executed by copying
+	the Pixmap's contents. Alternatively, it may forward the timelines,
+	acquire, and release points to an output sink directly, provided that
+	sink also supports explicit synchronization using DRM syncobjs.
+
+	The server may signal the release point without waiting for the acquire
+	point if the Pixmap's contents are never accessed while servicing the
+	request. This may happen, for example, if a request is discarded due to
+	it being fully occluded by a later request.
+
+	Beware that, if multiple Pixmaps are presented using the same release
+	timeline, the server makes no guarantees on the order in which the
+	release points will be signaled. Of particular concern is that, if the
+	later of the two release points is signaled before the earlier one, it
+	may appear to the client as though the Pixmap with the earlier release
+	point has been released before the server has finished its access to
+	it. Therefore, in general, clients are strongly advised to avoid using
+	the same release timeline with different Pixmaps.
+
+	If the server does not support PresentCapabilitySyncobj, a Value error
+	is generated.
+
+	If either 'acquire-syncobj' or 'release-syncobj' are None or do not
+	refer to previously imported syncobjs, a Value error is generated.
+
+	If 'acquire-point' or 'release-point' is zero, a Value error is
+	generated.
+
+	If 'acquire-syncobj' is equal to 'release-syncobj' and 'acquire-point'
+	is greater than or equal to 'release-point', a Value error is
+	generated.
+
 
 7.1 Requests proposed for a later Present extension version
 
@@ -729,6 +809,31 @@ A.2 Protocol Requests
 	4	SETofPRESENTCAPABILITY	capabilities
 └───
 
+┌───
+    PresentPixmapSynced
+	1	CARD8			major opcode
+	1	5			Present opcode
+	2	22+2n			length
+	4	Window			window
+	4	Pixmap			pixmap
+	4	CARD32			serial
+	4	Region			valid-area
+	4	Region			update-area
+	2	INT16			x-off
+	2	INT16			y-off
+	4	CRTC			target-crtc
+	4	SYNCOBJ			acquire-syncobj
+	4	SYNCOBJ			release-syncobj
+	8	CARD64			acquire-point
+	8	CARD64			release-point
+	4	CARD32			options
+	4				unused
+	8	CARD64			target-msc
+	8	CARD64			divisor
+	8	CARD64			remainder
+	8n	LISTofPresentNotify	notifies
+└───
+
 A.3 Protocol Events
 
 ┌───