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>

1 files changed, 107 insertions, 2 deletions

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
 
 ┌───