randr: add provider object (v8)

A provider object represents a GPU or virtual device that provides
rendering or output services to the X server. This protocol
allow controlling provider objects for output and offload slave devices.

v1.1: fix typo add missing define

v2: rename nProperties back to nAtoms, makes server simpler to c-n-p,
add missing Get request/reply

v3: bring back configure property, no point in diverging from the
output property code without good reason.
also fix typo pointed out on irc by rei4dan.

v3.1: drop cut-n-paste, increase RRNumberRequests

v4: reviewed by Aaron, address comments:
Fix provider error code
add missing notify, remove dri2 references, fix c-n-p issues.

v5: add provider change notify event with current role.
v5.1: fix cut-n-paste

v6:
document flags, fix whitespace, add better errors for SetProviderRoles,
add new events, fix pending language.

v6.1: add missing change notify event struct + missing padding

v7: fix a bunch more tab/spaces, add appendix sections for requests, events
and errors, remove multimaster flag in favour of max master counter,
move some members around to follow other events.

v7.1 fix maxMaster + wrong comment, one whitespace
v7.2 bump to being randr 1.4, fix some too generic names.
v7.3 remove dynamic flag, fix some language

v8 overhaul complete protocol, remove set provider roles, add specific
methods for setting offload sinks and output sources, add a list
of associated providers into the get provider info struct.

Earlier-review-by: Aaron Plattner <aplattner@nvidia.com>
Reviewed-by: Keith Packard <keithp@keithp.com>
Signed-off-by: Dave Airlie <airlied@redhat.com>

1 files changed, 518 insertions, 2 deletions

diff --git a/randrproto.txt b/randrproto.txt
index 7c297e2..6526b97 100644
--- a/randrproto.txt
+++ b/randrproto.txt
@@ -1,6 +1,6 @@
 	       The X Resize, Rotate and Reflect Extension
-			     Version 1.3.1
-			       2009-10-5
+			     Version 1.4.0
+			       2012-07-03
 
 			      Jim Gettys
 			   Jim.Gettys@hp.com
@@ -129,6 +129,26 @@ Version 1.4 adds an optional Border property.
      for compensating for the overscan behavior of certain
      televisions.
 
+Version 1.4 adds a new object called a provider object. A provider object
+represents a GPU or virtual device providing services to the X server.
+Providers have a set of abilities and a set of possible roles.
+
+Provider objects are used to control multi-GPU systems. Provider roles can
+be dynamically configured to provide support for:
+
+ 1) Output slaving: plug in a USB device, but have its output rendered
+ using the main GPU. On some dual-GPU laptops, the second GPU isn't
+ connected to the LVDS panel, so we need to use the first GPU as an output
+ slave for the second GPU. 
+
+ 2) offload - For dual-GPU laptops, allow direct rendered applications to be run
+ on the second GPU and display on the first GPU.
+
+ 3) GPU switching - Allow switching between two GPUs as the main screen
+ renderer.
+
+ 4) multiple GPU rendering - This replaces Xinerama.
+
 1.99 Acknowledgements
 
 Our thanks to the contributors to the design found on the xpert mailing
@@ -207,6 +227,8 @@ CRTC
 	A value for a CRTC argument does not name a defined CRTC.
 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.
 
 			      ❧❧❧❧❧❧❧❧❧❧❧
 
@@ -307,6 +329,19 @@ REFRESH { rates: LISTofCARD16 }
 
 			      ❧❧❧❧❧❧❧❧❧❧❧
 
+5.5. Protocol Types added in version 1.4 of the extension
+
+PROVIDER { XID }
+
+PROVIDER_CAPS { SourceOutput, SinkOutput, SourceOffload, SinkOffload }
+	Capabilties for this provider:
+	SourceOutput: This device can source output buffers.
+	SinkOutput: This device can sink output buffers.
+	SourceOffload: This device can source offload buffers.
+	SinkOffload: This device can sink offload buffers.
+
+			      ❧❧❧❧❧❧❧❧❧❧❧
+
 6. Extension Initialization
 
 The name of this extension is "RANDR".
@@ -1243,6 +1278,230 @@ dynamic changes in the display environment.
 
 			      ❧❧❧❧❧❧❧❧❧❧❧
 
+7.4 Extension Requests added in version 1.4 of the extension.
+
+┌───
+    RRGetProviders
+	window : WINDOW
+     ▶
+	timestamp: TIMESTAMP
+	providers: LISTofPROVIDER
+└───
+	Errors: Window
+
+	RRGetPRoviders returns the list of providers connected to the screen
+	associated with 'window'.
+
+	'timestamp' indicates when the configuration was last set.
+
+	'providers' contains the list of PROVIDERs associated with the
+	screen.
+
+┌───
+    RRGetProviderInfo
+	provider: PROVIDER
+     ▶
+	capabilities: PROVIDER_CAPS
+	name: STRING
+	crtcs: LISTofCRTC
+	outputs: LISTofOUTPUT
+	associated_providers: LISTofPROVIDERS
+	associated_provider_capability: LISTofPROVIDER_CAPS
+└───
+	Errors: Provider
+
+	RRGetProviderInfo return information about the specified provider.
+	The capabilites of the current provider are returned, along with
+	the list of providers currently associated with this provider and
+	the capability they are associated with. It also provides the list
+	of crtcs and outputs that this provider is responsible for.
+
+	'name' is a UTF-8 encoded string to be presented to the user to
+	indicate the device or driver supplied name.
+
+┌───
+    RRSetProviderOffloadSink
+	provider: PROVIDER
+	sink_provider: PROVIDER
+     ▶
+└───
+	Errors: Provider
+
+	RRSetOffloadSink sets the offload sink for this provider to the
+	specified provider.
+
+┌───
+    RRSetProviderOutputSource
+	provider: PROVIDER
+	source_provider: PROVIDER
+     ▶
+└───
+	Errors: Provider
+
+	RRSetOutputSource sets the output source for this provider to the
+	specified provider.
+
+┌───
+    RRListProviderProperties
+	provider:PROVIDERS
+      ▶
+	atoms: LISTof ATOM
+└───
+	Errors: Provider
+
+	This request returns the atoms of properties currently defined on
+	the provider.
+
+┌───
+    RRQueryProviderProperty
+	provider: PROVIDER
+	property: ATOM
+      ▶
+	pending: BOOL
+	range: BOOL
+	immutable: BOOL
+	valid-values: LISTofINT32
+└───
+	Errors: Name, Atom, Provider
+
+	If the specified property does not exist for the specified provider,
+	then a Name error is returned.
+
+	If 'pending' is TRUE, changes made to property values with
+	RRChangeProviderProperty will be saved in the pending property value
+	and be automatically copied to the current value on the next
+	RRSetCrtcConfig request on a crtc attached to that provider.
+	If 'pending' is	FALSE, changes are copied immediately.
+
+	If 'range' is TRUE, then the valid-values list will contain
+	precisely two values indicating the minimum and maximum allowed
+	values. If 'range' is FALSE, then the valid-values list will contain
+	the list of possible values; attempts to set other values will
+	result in a Value error.
+
+	If 'immutable' is TRUE, then the property configuration cannot be
+	changed by clients. Immutable properties are interpreted by the X
+	server.
+
+┌───
+    RRConfigureProviderProperty
+	provider: PROVIDER
+	property: ATOM
+	pending: BOOL
+	range: BOOL
+	valid-values: LISTofINT32
+└───
+	Errors: Access, Name, Atom, Provider
+
+	If the specified property is 'immutable', an Access error is
+	returned.
+
+	Otherwise, the configuration of the specified property is changed to
+	the values provided in this request.
+
+	If the specified property does not exist for the specified provider,
+	it is created with an empty value and None type.
+
+┌───
+    RRChangeProviderProperty
+	provider: PROVIDER
+	property, type: ATOM
+	format: {8, 16, 32}
+	mode: { Replace, Prepend, Append }
+	data: LISTofINT8 or LISTofINT16 or LISTofINT32
+└───
+	Errors: Alloc, Atom, Match, Value, Provider
+
+	This request alters the value of the property for the specified
+	provider. If the property is marked as a 'pending' property, only the
+	pending value of the property is changed. Otherwise, changes are
+	reflected in both the pending and current values of the property.
+	The type is uninterpreted by the server.  The format specifies
+	whether the data should be viewed as a list of 8-bit, 16-bit, or
+	32-bit quantities so that the server can correctly byte-swap as
+	necessary.
+
+	If the mode is Replace, the previous property value is discarded.
+	If the mode is Prepend or Append, then the type and format must
+	match the existing property value (or a Match error results).  If
+	the property is undefined, it is treated as defined with the correct
+	type and format with zero-length data.
+
+	For Prepend, the data is tacked on to the beginning of the existing
+	data, and for Append, it is tacked on to the end of the existing data.
+
+	This request generates a ProviderPropertyNotify
+
+	The lifetime of a property is not tied to the storing client.
+	Properties remain until explicitly deleted, until the provider is
+	destroyed, or until server reset (see section 10).
+
+	The maximum size of a property is server-dependent and may vary
+	dynamically.
+┌───
+    RRDeleteProviderProperty
+	provider: Provider
+	property: ATOM
+└───
+	Errors: Atom, Provider
+
+	This request deletes the property from the specified provider if the
+	property exists and generates a ProviderPropertyNotify event unless
+	the property does not exist.
+
+┌───
+    RRGetProviderProperty
+	provider: PROVIDER
+	property: ATOM
+	type: ATOM or AnyPropertyType
+	long-offset, long-length: CARD32
+	delete: BOOL
+	pending: BOOL
+      ▶
+	type: ATOM or None
+	format: {0, 8, 16, 32}
+	bytes-after: CARD32
+	value: LISTofINT8 or LISTofINT16 or LISTofINT32
+└───
+	Errors: Atom, Value, Provider
+
+	If the specified property does not exist for the specified provider,
+	then the return type is None, the format and bytes-after are zero,
+	and the value is empty.  The delete argument is ignored in this
+	case.
+
+	If the specified property exists but its type does not match the
+	specified type, then the return type is the actual type of the
+	property, the format is the actual format of the property (never
+	zero), the bytes-after is the length of the property in bytes (even
+	if the format is 16 or 32), and the value is empty.  The delete
+	argument is ignored in this case.
+
+	If the specified property exists and either AnyPropertyType is
+	specified or the specified type matches the actual type of the
+	property, then the return type is the actual type of the property,
+	the format is the actual format of the property (never zero), and
+	the bytes-after and value are as follows, given:
+
+		N = actual length of the stored property in bytes
+				  (even if the format is 16 or 32)
+		I = 4 × offset
+		T = N - I
+		L = MINIMUM(T, 4 × long-length)
+		A = N - (I + L)
+
+	If 'pending' is true, and if the property holds a pending value,
+	then the value returned will be the pending value of the property
+	rather than the current value.  The returned value starts at byte
+	index I in the property (indexing from 0), and its length in bytes
+	is L.  However, it is a Value error if long-offset is given such
+	that L is negative.  The value of bytes-after is A, giving the
+	number of trailing unread bytes in the stored property.  If delete
+	is True and the bytes-after is zero, the property is also deleted
+	from the provider, and a RRProviderPropertyNotify event is generated.
+
+
+			      ❧❧❧❧❧❧❧❧❧❧❧
 8. Extension Events
 
 Clients MAY select for ConfigureNotify on the root window to be
@@ -1379,6 +1638,56 @@ factors, such as re-cabling a monitor, etc.
 	just at the time when a display manager or log in script might
 	be changing the monitor size or configuration.
 
+8.2 Events added in version 1.4 of the RandR extension
+
+┌───
+    RRProviderChangeNotify:
+	timestamp: TIMESTAMP		time screen was reconfigured
+	config-timestamp: TIMESTAMP	time available config data was changed
+	window: WINDOW			window requesting notification
+	provider: PROVIDER		provider affected by change
+	role: CRTC			new role for provider
+└───
+
+	This event is generated whenever the role for a provider has changed
+	and is sent to requesting clients. 'timestamp' indicates when the
+	provider configuration was changed by a client.
+	'config-timestamp' says when the last time the available
+	configurations changed. 'root' is the root of the screen the change
+	occurred on, 'window' is window selecting for this event. The
+	precise change can be detected by examining the new state of the
+	system.
+
+┌───
+    RRProviderPropertyNotify:
+	window: WINDOW			window requesting notification
+	provider: PROVIDER		providre affected by change
+	atom: ATOM			affected property
+	time: TIMESTAMP			time property was changed
+	state: { NewValue, Deleted }	new property state
+└───
+
+	This event is reported to clients selecting RRProviderPropertyChange
+	on the window and is generated with state NewValue when a property
+	of the window is changed using RRChangeProviderProperty even when
+	adding zero-length data and when replacing all or part of a property
+	with identical data.  It is generated with state Deleted when a
+	property of the window is deleted using either
+	RRDeleteProviderProperty or RRGetProviderProperty.  The timestamp
+	indicates the server time when the property was changed.
+
+┌───
+    RRResourceChangeNotify:
+	window: WINDOW			window requesting notification
+	time: TIMESTAMP			time property was changed
+└───
+
+	This event is reported to clients selecting RRResourceChange
+	on the window and is generated whenever the set of available
+	RandR resources associated with the screen has changed, either
+	created or destroyed. Querying the list of available resources
+	with RRGetScreenResources and RRGetProviders will return the new set.
+
 			      ❧❧❧❧❧❧❧❧❧❧❧
 
 9. Properties
@@ -2388,6 +2697,178 @@ A.2.2 Protocol Requests added with version 1.3
 	4	CARD32			pad4
 └───
 
+A.2.3 Protocol Requests added with version 1.4
+
+┌───
+    RRGetProviders
+	1	CARD8			major opcode
+	1	32			RandR opcode
+	2	2			length
+	4	WINDOW			window
+      ▶
+	1	1			Reply
+	1				unused
+	2	CARD16			sequence number
+	4	CARD32			length
+	4	TIMESTAMP		timestamp
+	2	p			number of Providers
+	2	CARD16			maximum masters
+	4	CARD32			flags
+	4p	LISTofPROVIDERS		providers
+
+┌───
+    RRGetProviderInfo
+	1	CARD8			major opcode
+	1	33			RandR opcode
+	2	3			length
+	4	PROVIDER		provider
+	4	TIMESTAMP		config-timestamp
+      ▶
+	1	1			Reply
+	1	RRCONFIGSTATUS		status
+	2	CARD16			sequence number
+	4	1+c+o+(a*2)+(n+p)/4		reply length
+	4	TIMESTATMP		timestamp
+	4	CARD32			capabilites
+	2	c			number of crtcs
+	2	o 			number of outputs
+	2	a 			number of associated providers
+	2	n			length of name
+	4c	LISTofCRTC		crtcs
+	4o	LISTofOUTPUT		outputs
+	4a	LISTofPROVIDER		associated providers
+	4a	CARD32			associated provider capability
+	n	STRING8			name
+	p				unused, p=pad(n)
+
+┌───
+    RRSetProviderOffloadSink
+	1	CARD8			major opcode
+	1	34			RandR opcode
+	2	2			length
+	4	PROVIDER		provider
+	4	PROVIDER		offload sink provider
+	4	TIMESTAMP		timestamp
+┌───
+    RRSetProviderOutputSource
+	1	CARD8			major opcode
+	1	35			RandR opcode
+	2	2			length
+	4	PROVIDER		provider
+	4	PROVIDER		output source provider
+	4	TIMESTAMP		timestamp
+
+┌───
+    RRListProviderProperties
+	1	CARD8			major opcode
+	1	36			RandR opcode
+	2	2			length
+	4	PROVIDER		provider
+      ▶
+	1	1			Reply
+	1				unused
+	2	CARD16			sequence number
+	4	n			reply length
+	2	n			number of ATOMs in atoms
+	22				unused
+	4n	LISTofATOM		atoms
+└───
+┌───
+    RRQueryProviderProperty
+	1	CARD8			major opcode
+	1	37			RandR opcode
+	2	3			request length
+	4	PROVIDER		provider
+	4	ATOM			property
+      ▶
+	1	1			Reply
+	1				unused
+	2	CARD16			sequence number
+	4	n			reply length
+	1	BOOL			pending
+	1	BOOL			range
+	1	BOOL			immutable
+	21				unused
+	4n	LISTofINT32		valid values
+└───
+┌───
+    RRConfigureProviderProperty
+	1	CARD8			major opcode
+	1	38			RandR opcode
+	2	4+n			request length
+	4	PROVIDER		provider
+	4	ATOM			property
+	1	BOOL			pending
+	1	BOOL			range
+	2				unused
+	4n	LISTofINT32		valid values
+└───
+┌───
+    RRChangeProviderProperty
+	1	CARD8			major opcode
+	1	39			RandR opcode
+	2	6+(n+p)/4		request length
+	4	PROVIDER		provider
+	4	ATOM			property
+	4	ATOM			type
+	1	CARD8			format
+	1				mode
+		0	Replace
+		1	Prepend
+		2	Append
+	2				unused
+	4	CARD32			length of data in format units
+					(= n for format = 8)
+					(= n/2 for format = 16)
+					(= n/4 for format = 32)
+	n	LISTofBYTE		data
+					(n is a multiple of 2 for format = 16)
+					(n is a multiple of 4 for format = 32)
+	p				unused, p=pad(n)
+└───
+┌───
+    RRDeleteProviderProperty
+	1	CARD8			major opcode
+	1	40			RandR opcode
+	2	3			request length
+	4	PROVIDER		provider
+	4	ATOM			property
+└───
+┌───
+    RRGetProviderProperty
+	1	CARD8			major opcode
+	1	41			RandR opcode
+	2	7			request length
+	4	PROVIDER		provider
+	4	ATOM			property
+	4	ATOM			type
+		0	AnyPropertyType
+	4	CARD32			long-offset
+	4	CARD32			long-length
+	1	BOOL			delete
+	1	BOOL			pending
+	2				unused
+      ▶
+	1	1			Reply
+	1	CARD8			format
+	2	CARD16			sequence number
+	4	(n+p)/4			reply length
+	4	ATOM			type
+		0	None
+	4	CARD32			bytes-after
+	4	CARD32			length of value in format units
+					(= 0 for format = 0)
+					(= n for format = 8)
+					(= n/2 for format = 16)
+					(= n/4 for format = 32)
+	12				unused
+	n	LISTofBYTE		value
+					(n is zero for format = 0)
+					(n is a multiple of 2 for format = 16)
+					(n is a multiple of 4 for format = 32)
+	p				unused, p=pad(n)
+└───
+
 A.3 Protocol Events
 
 ┌───
@@ -2455,6 +2936,40 @@ A.3.1 Protocol Events added with version 1.2
 	11				unused
 └───
 
+A.3.2 Protocol Events added with version 1.4
+┌───
+    RRProviderChangeNotify
+	1	Base + 1		code
+	1	1			sub-code
+	2	CARD16			sequence number
+	4	TIMESTAMP		timestamp
+	4	WINDOW			request window
+	4	PROVIDER		provider affected
+	16				unused
+└───
+┌───
+    RRProviderPropertyNotify
+	1	Base + 1		code
+	1	2			sub-code
+	2	CARD16			sequence number
+	4	WINDOW			window
+	4	PROVIDER		provider
+	4	ATOM			atom
+	4	TIMESTAMP		time
+	1				state
+		0	NewValue
+		1	Deleted
+	11				unused
+└───
+┌───
+    RRResourceChangeNotify
+	1	Base + 1		code
+	1	2			sub-code
+	2	CARD16			sequence number
+	4	TIMESTAMP		time
+	4	WINDOW			window
+	20				unused
+└───
 A.4 Protocol Errors
 
 ┌───
@@ -2462,6 +2977,7 @@ A.4 Protocol Errors
 	Base + 0		Output
 	Base + 1		Crtc
 	Base + 2		Mode
+	Base + 3		Provider
 └───
 
 Bibliography