From e941ffc9ebc3a6659ce757fb510ef60b61244020 Mon Sep 17 00:00:00 2001
From: Christoph Haag <haagch@frickel.club>
Date: Sat, 10 Feb 2018 21:20:56 +0100
Subject: [PATCH 1/3] [PATCH randrproto 1/2] Add Leases. [v3]

A "lease" is a set of crtc and output resources granted to another
application for use outside of X. These will not be usable through the
X protocol until the lease terminates. Leased outputs will be seen as
disconnected, leased CRTCs will be seen as not usable with any output.

v2:
	Delete output grabs
	Add LeaseNotify events
	Add FreeLease with option to terminate

v3:
	Clarify a couple of lease behaviors:

	* You can lease an in-use object, it makes the X server stop
	  using it, you don't get an error back.

	* There's no explicit 'Disabled' state for a crtc, when a crtc
	  is disabled, it just has a set of reported values for
	  GetCrtcInfo.

Signed-off-by: Keith Packard <keithp@keithp.com>
---
 include/X11/extensions/randr.h      | 15 ++++--
 include/X11/extensions/randrproto.h | 57 +++++++++++++++++++++++
 randrproto.txt                      | 93 +++++++++++++++++++++++++++++++++++--
 3 files changed, 157 insertions(+), 8 deletions(-)

diff --git a/include/X11/extensions/randr.h b/include/X11/extensions/randr.h
index 6fcda87..e53cd56 100644
--- a/include/X11/extensions/randr.h
+++ b/include/X11/extensions/randr.h
@@ -40,11 +40,11 @@ typedef unsigned long	XRandrModeFlags;
 
 #define RANDR_NAME		"RANDR"
 #define RANDR_MAJOR		1
-#define RANDR_MINOR		5
+#define RANDR_MINOR		6
 
-#define RRNumberErrors		4
+#define RRNumberErrors		5
 #define RRNumberEvents		2
-#define RRNumberRequests	45
+#define RRNumberRequests	47
 
 #define X_RRQueryVersion	0
 /* we skip 1 to make old clients fail pretty immediately */
@@ -109,6 +109,10 @@ typedef unsigned long	XRandrModeFlags;
 #define X_RRSetMonitor		      43
 #define X_RRDeleteMonitor	      44
 
+/* v1.6 */
+#define X_RRCreateLease		      45
+#define X_RRFreeLease		      46
+
 /* Event selection bits */
 #define RRScreenChangeNotifyMask  (1L << 0)
 /* V1.2 additions */
@@ -119,6 +123,8 @@ typedef unsigned long	XRandrModeFlags;
 #define RRProviderChangeNotifyMask   (1L << 4)
 #define RRProviderPropertyNotifyMask (1L << 5)
 #define RRResourceChangeNotifyMask   (1L << 6)
+/* V1.6 additions */
+#define RRLeaseNotifyMask            (1L << 7)
 
 /* Event codes */
 #define RRScreenChangeNotify	0
@@ -131,6 +137,8 @@ typedef unsigned long	XRandrModeFlags;
 #define  RRNotify_ProviderChange    3
 #define  RRNotify_ProviderProperty  4
 #define  RRNotify_ResourceChange    5
+/* V1.6 additions */
+#define  RRNotify_Lease             6
 /* used in the rotation field; rotation and reflection in 0.1 proto. */
 #define RR_Rotate_0		1
 #define RR_Rotate_90		2
@@ -172,6 +180,7 @@ typedef unsigned long	XRandrModeFlags;
 #define BadRRCrtc		1
 #define BadRRMode		2
 #define BadRRProvider		3
+#define BadRRLease		4
 
 /* Conventional RandR output properties */
 
diff --git a/include/X11/extensions/randrproto.h b/include/X11/extensions/randrproto.h
index 48be7aa..712c8b5 100644
--- a/include/X11/extensions/randrproto.h
+++ b/include/X11/extensions/randrproto.h
@@ -50,6 +50,7 @@
 #define RRCrtc CARD32
 #define RRProvider CARD32
 #define RRModeFlags CARD32
+#define RRLease CARD32
 
 #define Rotation CARD16
 #define SizeID CARD16
@@ -835,6 +836,46 @@ typedef struct {
 } xRRGetProviderPropertyReply;
 #define sz_xRRGetProviderPropertyReply	32
 
+/*
+ * Additions for V1.6
+ */
+
+typedef struct {
+    CARD8	reqType;
+    CARD8	randrReqType;
+    CARD16	length B16;
+    Window	window B32;
+    RRLease	lid B32;
+    CARD16	nCrtcs B16;
+    CARD16	nOutputs B16;
+} xRRCreateLeaseReq;
+#define sz_xRRCreateLeaseReq	16
+
+typedef struct {
+    BYTE	type;
+    CARD8	nfd;
+    CARD16	sequenceNumber B16;
+    CARD32	length B32;
+    CARD32	pad2 B32;
+    CARD32	pad3 B32;
+    CARD32	pad4 B32;
+    CARD32	pad5 B32;
+    CARD32	pad6 B32;
+    CARD32	pad7 B32;
+} xRRCreateLeaseReply;
+#define sz_xRRCreateLeaseReply		32
+
+typedef struct {
+    CARD8	reqType;
+    CARD8	randrReqType;
+    CARD16	length B16;
+    RRLease	lid B32;
+    BYTE	terminate;
+    CARD8	pad1;
+    CARD16	pad2 B16;
+} xRRFreeLeaseReq;
+#define sz_xRRFreeLeaseReq		12
+
 /*
  * event
  */
@@ -948,6 +989,22 @@ typedef struct {
 } xRRResourceChangeNotifyEvent;
 #define sz_xRRResourceChangeNotifyEvent	32
 
+typedef struct {
+    CARD8 type;				/* always evBase + RRNotify */
+    CARD8 subCode;			/* RRNotify_Lease */
+    CARD16 sequenceNumber B16;
+    Time timestamp B32;			/* time resource was changed */
+    Window window B32;			/* window requesting notification */
+    RRLease lease B32;
+    CARD8 created;			/* created/deleted */
+    CARD8 pad0;
+    CARD16 pad1 B16;
+    CARD32 pad2 B32;
+    CARD32 pad3 B32;
+    CARD32 pad4 B32;
+} xRRLeaseNotifyEvent;
+#define sz_xRRLeaseNotifyEvent		32
+
 typedef struct {
     CARD8	reqType;
     CARD8	randrReqType;
diff --git a/randrproto.txt b/randrproto.txt
index c06bc90..4c0990a 100644
--- a/randrproto.txt
+++ b/randrproto.txt
@@ -1,6 +1,6 @@
 	       The X Resize, Rotate and Reflect Extension
-			     Version 1.5.0
-			       2015-03-14
+			     Version 1.6.0
+			       2017-04-01
 
 			      Jim Gettys
 			   Jim.Gettys@hp.com
@@ -9,9 +9,7 @@
 			Hewlett Packard Company
 
 			     Keith Packard
-			keith.packard@intel.com
-		     Open Source Technology Center
-			   Intel Corporation
+			  keithp@keithp.com
 
 1. Introduction
 
@@ -194,6 +192,16 @@ XID BadMatch when a RandR output disappears. This is to clarify that
 going forward the X server will not remove outputs dynamically,
 just mark them as disconnected.
 
+1.6. Introduction to version 1.6 of the extension
+
+Version 1.6 adds resource leasing.
+
+ • A 'Lease' is a collection of crtcs and outputs which are made
+   available to a client for direct access via kernel KMS and DRM
+   APIs. This is done by passing a suitable file descriptor back to
+   the client which has access to those resources. While leased, those
+   resources aren't used by the X server.
+
 1.99 Acknowledgments
 
 Our thanks to the contributors to the design found on the xpert mailing
@@ -280,6 +288,8 @@ Mode
 	A value for a MODE argument does not name a defined MODE.
 Provider
 	A value for a PROVIDER argument does not name a defined PROVIDER.
+Lease
+	A value for a LEASE argument does not name a defined LEASE
 
 			      ❧❧❧❧❧❧❧❧❧❧❧
 
@@ -427,6 +437,12 @@ MONITORINFO { name: ATOM
 
 			      ❧❧❧❧❧❧❧❧❧❧❧
 
+5.7. Protocol Types added in version 1.6 of the extension
+
+LEASE { XID }
+
+			      ❧❧❧❧❧❧❧❧❧❧❧
+
 6. Extension Initialization
 
 The name of this extension is "RANDR".
@@ -1674,6 +1690,57 @@ dynamic changes in the display environment.
 	window of the screen.
 
 			      ❧❧❧❧❧❧❧❧❧❧❧
+
+7.6. Extension Requests added in version 1.6 of the extension.
+
+┌───
+    RRCreateLease
+	window : WINDOW
+	lid: LEASE
+	crtcs: LISTofCRTC
+	outputs: LISTofOUTPUT
+     ▶
+	nfd: CARD8
+	lease: FD
+└───
+	Errors: IdChoice, Window, Access, Value, CRTC, Output
+
+	Creates a new Lease called 'lid' for the specified crtcs and
+	outputs from the screen defined by 'window'. Returns a KMS/DRM
+	file descriptor which can control the leased objects directly
+	through the kernel. While leased, all resources will appear to
+	be 'useless' to clients other than the leasing client as
+	follows:
+
+	• Crtcs are reported as having no 'possible-outputs' and all
+	  other values reported as if the crtc were disabled.
+
+	• Outputs are reported as having no crtcs they can be
+	  connected to, no clones they can share a crtc with, will
+	  report a connection status of Disconnected, and will show
+	  the current crtc as if it were disabled.
+
+	The lease remains in effect until the file descriptor is
+	closed, even if the client holding the lease disconnects from
+	the X server.
+
+	Returns an Access error if any of the named resources are
+	already leased to another client.
+
+┌───
+    RRFreeLease
+	lid: LEASE
+	terminate: BOOL
+└───
+	Errors: Lease
+
+	Frees the reference to the lease 'lid'. If 'terminate' is
+	true, then the lease is terminated and all leased resources
+	returned to the X server. If 'terminate' is false, then the
+	lease remains in effect, but the X server no longer has a name
+	for it.
+
+			      ❧❧❧❧❧❧❧❧❧❧❧
 8. Extension Events
 
 Clients MAY select for ConfigureNotify on the root window to be
@@ -1855,6 +1922,21 @@ factors, such as re-cabling a monitor, etc.
 	created or destroyed. Querying the list of available resources
 	with RRGetScreenResources and RRGetProviders will return the new set.
 
+8.3 Events added in version 1.6 of the RandR extension
+
+┌───
+    RRLeaseNotify:
+	timestamp : TIMESTAMP		time screen was reconfigured
+	window : WINDOW			window requesting notification
+	lease : LEASE			lease
+	created : BOOL			created/destroyed indicator
+└───
+
+	This event is generated whenever a lease has been created or
+	destroyed and is sent to requesting clients. 'timestamp'
+	indicates when the change happend.  'window' is the window
+	selecting for this event.
+
 			      ❧❧❧❧❧❧❧❧❧❧❧
 
 9. Properties
@@ -2286,6 +2368,7 @@ A.1 Common Types
 	0x0010	ProviderChangeNotifyMask 	Added in version 1.4
 	0x0020	ProviderPropertyNotifyMask	Added in version 1.4
 	0x0040	ResourceChangeNotifyMask	Added in version 1.4
+	0x0080  LeaseNotifyMask                 Added in version 1.6
 
 └───
       Event select mask for RRSelectInput
-- 
2.16.1

