Proposal for RandR version 1.6, Leases [v2]

Submitted by Keith Packard on April 29, 2017, 5:52 a.m.

Details

Message ID 861ssb7oay.fsf@hiro.keithp.com
State New
Headers show
Series "Proposal for RandR version 1.6, Leases and EDID-based output grabs" ( rev: 2 ) in DRI devel

Not browsing as part of any series.

Commit Message

Keith Packard April 29, 2017, 5:52 a.m.
Keith Packard <keithp@keithp.com> writes:

With the changes to the kernel interface, and discussion about how to
mask HMD outputs from X applications still ongoing, I've ripped the
grabs out of the protocol and will add whatever we come up with back at
some point.

In any case, there are just two requests now, CreateLease and
FreeLease. There are also events delivered when leases are created or
destroyed so a client can see when the lease holder dies. Leases are
named with XIDs so the client can tell lease has died. When the lease
creator frees a lease, the actual lease (may) stay around; you don't get
events on those as they no longer have an XID.

The kernel doesn't (yet) support a lessor terminating a lease; I think
that's something we'll probably want, so I added it to this protocol
as a point of discussion.

Oh, and all of the code is up and running, so this is more real than it
was a couple of weeks ago.

Here's the patch to the protocol and protocol headers. Once this looks
reasonable, I'll send out the xcb and X server patches to match.

Patch hide | download patch | download mbox

From 882cf1f11f3b398b00cb09f49aa7d0714434354f Mon Sep 17 00:00:00 2001
From: Keith Packard <keithp@keithp.com>
Date: Fri, 28 Apr 2017 22:32:44 -0700
Subject: [PATCH] Add Leases.

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.

Signed-off-by: Keith Packard <keithp@keithp.com>
---
 configure.ac   |  2 +-
 randr.h        | 15 +++++++--
 randrproto.h   | 58 +++++++++++++++++++++++++++++++++++
 randrproto.txt | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 4 files changed, 162 insertions(+), 9 deletions(-)

diff --git a/configure.ac b/configure.ac
index 18197e3..4464e88 100644
--- a/configure.ac
+++ b/configure.ac
@@ -22,7 +22,7 @@  dnl
 dnl Process this file with autoconf to create configure.
 
 AC_PREREQ([2.60])
-AC_INIT([RandrProto], [1.5.0],
+AC_INIT([RandrProto], [1.6.0],
         [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg])
 AM_INIT_AUTOMAKE([foreign dist-bzip2])
 
diff --git a/randr.h b/randr.h
index 6fcda87..e53cd56 100644
--- a/randr.h
+++ b/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/randrproto.h b/randrproto.h
index 114a624..a0b04d3 100644
--- a/randrproto.h
+++ b/randrproto.h
@@ -51,6 +51,7 @@ 
 #define RRProvider CARD32
 #define RRModeFlags CARD32
 #define Atom CARD32
+#define RRLease CARD32
 
 #define Rotation CARD16
 #define SizeID CARD16
@@ -837,6 +838,46 @@  typedef struct {
 #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
  */
 typedef struct {
@@ -950,6 +991,23 @@  typedef struct {
 #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;
+    CARD32 pad5 B32;
+} xRRLeaseNotifyEvent;
+#define sz_xRRLeaseNotifyEvent		32
+
+typedef struct {
     CARD8	reqType;
     CARD8	randrReqType;
     CARD16	length B16;
diff --git a/randrproto.txt b/randrproto.txt
index 74b7c36..7312e0b 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
 
@@ -186,6 +184,16 @@  consider as single viewable areas.
 Xinerama's information now comes from the Monitors instead of directly
 from the CRTCs. The Monitor marked as Primary will be listed first.
 
+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
@@ -272,6 +280,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
 
 			      ❧❧❧❧❧❧❧❧❧❧❧
 
@@ -419,6 +429,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".
@@ -1666,6 +1682,60 @@  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 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 in
+	use or already leased to another client.
+
+	Returns a Match error if any of the named resources are in use
+	by the X server.
+
+┌───
+    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
@@ -1847,6 +1917,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
@@ -2278,6 +2363,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.11.0