From ef99bda581449d6c8dab7233e287c7bfd578730c Mon Sep 17 00:00:00 2001 From: Dave Airlie Date: Fri, 20 Jan 2012 17:38:16 +0000 Subject: 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 Reviewed-by: Keith Packard Signed-off-by: Dave Airlie --- randrproto.txt | 520 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 518 insertions(+), 2 deletions(-) (limited to 'randrproto.txt') 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 -- cgit v1.2.3