Add screen-specific privates.

Screen-specific privates areas are only allocated for objects related
to the target screen; objects allocated for other screens will not
have the private space reserved. This saves memory in these objects
while also allowing hot-plug screens to have additional private
allocation space beyond what the core screens are using.

Drivers are encouraged to switch to this mechanism as it will reduce
memory usage in multi-GPU environments, but it is only required for
drivers which will be loaded after the server starts, like
modesetting.

Objects providing screen-specific privates *must* be managed by the
screen-specific private API when allocating or initializing privates
so that the per-screen area can be initialized properly.

The objects which support screen-specific privates are:

	Windows
	Pixmaps
	GCs
	Pictures

Extending this list to include Colormaps would be possible, but
require slightly more work as the default colormap is created before
all colormap privates are allocated during server startup, and hence
gets a bunch of special treatment.

Of particular note, glyphs are *not* capable of supporting
screen-specific privates as they are global objects, not allocated on
a screen-specific basis, and so each driver must be able to see their
privates within the glyph.

Signed-off-by: Keith Packard <keithp@keithp.com>
Reviewed-by: Dave Airlie <airlied@redhat.com>

1 files changed, 25 insertions, 1 deletions

diff --git a/doc/Xserver-spec.xml b/doc/Xserver-spec.xml
index 31b6fb05d..cd1a9d07a 100644
--- a/doc/Xserver-spec.xml
+++ b/doc/Xserver-spec.xml
@@ -109,6 +109,12 @@
 	<revremark>Revised for Xorg 1.9 devPrivates changes
 	  and 1.8 CreateNewResourceType changes</revremark>
       </revision>
+      <revision>
+	<revnumber>3.6</revnumber>
+	<date>July 2012</date>
+	<authorinitials>kp</authorinitials>
+	<revremark>Revised for X server 1.13 screen-specific devPrivates changes</revremark>
+      </revision>
     </revhistory>
     <abstract>
       <para>The following document explains the structure of the X Window System display server and the interfaces among the larger pieces.  It is intended as a reference for programmers who are implementing an X Display Server on their workstation hardware.  It is included with the X Window System source tape, along with the document "Strategies for Porting the X v11 Sample Server."  The order in which you should read these documents is:
@@ -4714,7 +4720,8 @@ Two new extensibility concepts have been developed for release 4, Wrappers
 and devPrivates.  These replace the R3 GCInterest queues, which were not a
 general enough mechanism for many extensions and only provided hooks into a
 single data structure.  devPrivates have been revised substantially for
-X.Org X server release 1.5, and updated again for the 1.9 release.</para>
+X.Org X server release 1.5, updated again for the 1.9 release and extended
+again for the 1.13 relealse.</para>
 <section>
   <title>devPrivates</title>
 <para>
@@ -4758,6 +4765,23 @@ the specified type with distinct storage for the given
 that are otherwise equivalent to the following Private functions.</para>
 
 <para>
+  To request private space in objects created for a specific screen, use
+  <blockquote><programlisting>
+    Bool dixRegisterScreenSpecificPrivateKey(ScreenPtr pScreen, DevPrivateKey key, DevPrivateType type, unsigned size);
+  </programlisting></blockquote>
+  The <parameter>type</parameter> and <parameter>size</parameter> arguments are
+  the same as those to <function>dixRegisterPrivateKey</function> but this
+  function ensures only that the given <parameter>key</parameter> exists on objects of
+  the specified type that are allocated with reference to the specified
+  <parameter>pScreen</parameter>. Using the key on objects allocated for
+  other screens will result in incorrect results; there is no check made to
+  ensure that the caller's screen matches the private's screen. The key is
+  usable in any of the following functions. Screen-specific private storage is available
+  only for Windows, GCs, Pixmaps and Pictures. Attempts to allocate screen-specific
+  privates on other objects will result in a call to FatalError.
+</para>
+
+<para>
 To attach a piece of private data to an object, use:
 <blockquote><programlisting>
 	void dixSetPrivate(PrivateRec **privates, const DevPrivateKey key, pointer val)