xserver: Branch 'master' - 5 commits
Keith Packard
keithp at kemper.freedesktop.org
Mon Aug 9 21:27:39 PDT 2010
doc/xml/Xserver-spec.xml | 152 +++++++++++++++++++++++++---------------------
doc/xml/dtrace/.gitignore | 4 +
doc/xml/xmlrules.in | 2
include/privates.h | 4 -
4 files changed, 92 insertions(+), 70 deletions(-)
New commits:
commit 35c0dbe4b0a6ab790f4271325b8a0b16894daa8b
Author: Gaetan Nadon <memsize at videotron.ca>
Date: Sun Aug 8 10:03:08 2010 -0400
doc: add missing .gitignore for Xserver-DTrace
The dtrace doc was recently added in commit
9c171d4aee695ab66e6db1ab92539557bd368cfa
Reviewed-by: Alan Coopersmith <alan.coopersmith at oracle.com>
Signed-off-by: Gaetan Nadon <memsize at videotron.ca>
diff --git a/doc/xml/dtrace/.gitignore b/doc/xml/dtrace/.gitignore
new file mode 100644
index 0000000..a43c4e1
--- /dev/null
+++ b/doc/xml/dtrace/.gitignore
@@ -0,0 +1,4 @@
+Xserver-DTrace.html
+Xserver-DTrace.pdf
+Xserver-DTrace.txt
+xorg.css
commit 05c4fe83fdc20b838fd59658478278dc31a55eb9
Author: Alan Coopersmith <alan.coopersmith at oracle.com>
Date: Fri Jul 30 17:43:24 2010 -0700
Check HAVE_XMLTO_TEXT before trying to use xmlto to make text files
Reported-by: Matt Turner <mattst88 at gmail.com>
Tested-by: Gaetan Nadon <memsize at videotron.ca>
Signed-off-by: Alan Coopersmith <alan.coopersmith at oracle.com>
diff --git a/doc/xml/xmlrules.in b/doc/xml/xmlrules.in
index 0d094be..b7fda11 100644
--- a/doc/xml/xmlrules.in
+++ b/doc/xml/xmlrules.in
@@ -48,10 +48,12 @@ xorg.css: $(STYLESHEET_SRCDIR)/xorg.css
endif
if HAVE_XMLTO
+if HAVE_XMLTO_TEXT
BUILT_DOC_FILES += $(TXT_FILES)
.xml.txt:
@rm -f $@
$(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) txt $<
+endif
BUILT_DOC_FILES += $(HTML_FILES)
.xml.html:
commit a6fb7829ed9bf26c4c2a02c6ed075fb1b17f7b2a
Author: Alan Coopersmith <alan.coopersmith at oracle.com>
Date: Mon Jul 26 19:55:27 2010 -0700
Xserver-spec: Update ChangeGC prototype, add ChangeGCXIDs
Signed-off-by: Alan Coopersmith <alan.coopersmith at oracle.com>
Reviewed-by: Jamey Sharp <jamey at minilop.net>
diff --git a/doc/xml/Xserver-spec.xml b/doc/xml/Xserver-spec.xml
index c5fd191..563705f 100644
--- a/doc/xml/Xserver-spec.xml
+++ b/doc/xml/Xserver-spec.xml
@@ -3760,7 +3760,7 @@ Also included in each GC is support for dynamic devPrivates, which the
DDX can use for any purpose (see <xref linkend="wrappers_and_privates"/> below).</para>
<para>
The DIX routines available for manipulating GCs are
-CreateGC, ChangeGC, CopyGC, SetClipRects, SetDashes, and FreeGC.
+CreateGC, ChangeGC, ChangeGCXIDs, CopyGC, SetClipRects, SetDashes, and FreeGC.
<blockquote><programlisting>
GCPtr CreateGC(pDrawable, mask, pval, pStatus)
@@ -3769,10 +3769,17 @@ CreateGC, ChangeGC, CopyGC, SetClipRects, SetDashes, and FreeGC.
XID *pval;
int *pStatus;
- int ChangeGC(pGC, mask, pval)
+ int ChangeGC(client, pGC, mask, pUnion)
+ ClientPtr client;
GCPtr pGC;
BITS32 mask;
- XID *pval;
+ ChangeGCValPtr pUnion;
+
+ int ChangeGCXIDs(client, pGC, mask, pC32)
+ ClientPtr client;
+ GCPtr pGC;
+ BITS32 mask;
+ CARD32 *pC32;
int CopyGC(pgcSrc, pgcDst, mask)
GCPtr pgcSrc;
commit a817271d461e2f95dd7dc62cd1c7d123ce92f555
Author: Alan Coopersmith <alan.coopersmith at oracle.com>
Date: Thu Jul 22 23:57:57 2010 -0700
Update Xserver-spec for new devPrivates API
Signed-off-by: Alan Coopersmith <alan.coopersmith at oracle.com>
Reviewed-by: Patrick E. Kane <pekane52 at gmail.com>
diff --git a/doc/xml/Xserver-spec.xml b/doc/xml/Xserver-spec.xml
index 466b79d..c5fd191 100644
--- a/doc/xml/Xserver-spec.xml
+++ b/doc/xml/Xserver-spec.xml
@@ -92,6 +92,13 @@
<authorinitials>efw</authorinitials>
<revremark>Revised for devPrivates changes</revremark>
</revision>
+ <revision>
+ <revnumber>3.5</revnumber>
+ <date>July 2010</date>
+ <authorinitials>ac</authorinitials>
+ <revremark>Revised for Xorg 1.9 devPrivates changes
+ and 1.8 CreateNewResourceType changes</revremark>
+ </revision>
</revhistory>
<legalnotice>
<para>Copyright © 1994 X Consortium, Inc., 2004 X.org Foundation, Inc.</para>
@@ -4808,32 +4815,68 @@ 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 relase 1.5.</para>
+X.Org X server release 1.5, and updated again for the 1.9 release.</para>
<section>
<title>devPrivates</title>
<para>
devPrivates provides a way to attach arbitrary private data to various server structures.
Any structure which contains a <structfield>devPrivates</structfield> field of
-type <type>PrivateRec</type> supports this mechanism. Private data can be allocated at
-any time during an object's life cycle and callbacks are available to initialize and clean
-up allocated space.</para>
+type <type>PrivateRec</type> supports this mechanism. Some structures allow
+allocating space for private data after some objects have been created, others
+require all space allocations be registered before any objects of that type
+are created. <filename class="headerfile">Xserver/include/privates.h</filename>
+lists which of these cases applies to each structure containing
+<structfield>devPrivates</structfield>.</para>
+
+<para>
+To request private space, use
+<blockquote><programlisting>
+ Bool dixRegisterPrivateKey(DevPrivateKey key, DevPrivateType type, unsigned size);
+</programlisting></blockquote>
+The first argument is a pointer to a <type>DevPrivateKeyRec</type> which
+will serve as the unique identifier for the private data. Typically this is
+the address of a static <type>DevPrivateKeyRec</type> in your code.
+The second argument is the class of objects for which this key will apply.
+The third argument is the size of the space being requested, or
+<constant>0</constant> to only allocate a pointer that the caller will manage.
+If space is requested, this space will be automatically freed when the object
+is destroyed. Note that a call to <function>dixSetPrivate</function>
+that changes the pointer value may cause the space to be unreachable by the caller, however it will still be automatically freed.
+The function returns <literal>TRUE</literal> unless memory allocation fails.
+If the function is called more than once on the same key, all calls must use
+the same value for <type>size</type> or the server will abort.</para>
+
+<para>
+To request private space and have the server manage the key, use
+<blockquote><programlisting>
+ DevPrivateKey dixCreatePrivateKey(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 allocates a <type>DevPrivateKeyRec</type> and returns a pointer to it
+instead of requiring the caller to pass a pointer to an existing structure.
+The server will free it automatically when the privates system is restarted
+at server reset time.</para>
+
<para>
To attach a piece of private data to an object, use:
<blockquote><programlisting>
- int dixSetPrivate(PrivateRec **privates, const DevPrivateKey key, pointer val)
+ void dixSetPrivate(PrivateRec **privates, const DevPrivateKey key, pointer val)
</programlisting></blockquote>
-The first argument is the address of the <structfield>devPrivates</structfield> field
-in the target structure. This field is managed privately by the DIX layer and
-should not be directly modified. The second argument is some address value which
-will serve as the unique identifier for the private data. Typically this is the address
-of some global variable in your code. Only one piece of data with a given key can be attached to an object. However, you
-can use the same key to store data in any object that supports the devPrivates mechanism. The third
-argument is the value to store.</para>
+The first argument is the address of the <structfield>devPrivates</structfield>
+field in the target structure. This field is managed privately by the DIX
+layer and should not be directly modified. The second argument is a pointer
+to the <type>DevPrivateKeyRec</type> which you registered with
+<function>dixRegisterPrivateKey</function> or allocated with
+<function>dixCreatePrivateKey</function>. Only one
+piece of data with a given key can be attached to an object, and in most cases
+each key is specific to the type of object it was registered for. (An
+exception is the PRIVATE_XSELINUX class which applies to multiple object types.)
+The third argument is the value to store.</para>
<para>
-If private data with the given key is already associated with the object, <function>dixSetPrivate</function> will
-overwrite the old value with the new one. Otherwise, new space will be allocated to hold the pointer value.
-The function returns <literal>TRUE</literal> unless memory allocation fails, but note that since memory allocation only
-occurs on the first reference to the private data, all subsequent calls are guaranteed to succeed.</para>
+If private data with the given key is already associated with the object,
+<function>dixSetPrivate</function> will overwrite the old value with the
+new one.</para>
<para>
To look up a piece of private data, use one of:
@@ -4842,56 +4885,22 @@ To look up a piece of private data, use one of:
pointer *dixLookupPrivateAddr(PrivateRec **privates, const DevPrivateKey key)
</programlisting></blockquote>
The first argument is the address of the <structfield>devPrivates</structfield> field
-in the target structure. The second argument is the key to look up. If private data with the given key is already associated
-with the object, <function>dixLookupPrivate</function> will return the stored pointer value while <function>dixLookupPrivateAddr</function>
-will return the address of the stored pointer. Otherwise, new space will be first allocated to hold the pointer value
-and it will be initialized to NULL. Both functions return <literal>NULL</literal> if memory allocation fails, but note that
-since memory allocation only occurs on the first reference to the private data, all subsequent calls are guaranteed to succeed.</para>
-
-<para>
-To request pre-allocated private space, use
-<blockquote><programlisting>
- int dixRequestPrivate(const DevPrivateKey key, unsigned size)
-</programlisting></blockquote>
-The first argument is the key for which space is being requested. The second argument is the size of the space being requested.
-After this function has been called,
-future calls to <function>dixLookupPrivate</function> or <function>dixLookupPrivateAddr</function> that cause the private pointer
-to be initially allocated will also allocate <varname>size</varname> bytes of space cleared to zero and initialize the private pointer to point
-to this space instead of <literal>NULL</literal>. This space will be automatically freed. Note that a call to <function>dixSetPrivate</function>
-that changes the pointer value may cause the space to be unreachable by the caller, however it will still be automatically freed.
-The function returns <literal>TRUE</literal> unless memory allocation fails. If the function is called more than once, the largest value
-of <type>size</type> is used.</para>
-
-<para>
-To set callbacks for initializing and cleaning up private space, use
-<blockquote><programlisting>
- typedef struct {
- DevPrivateKey key;
- pointer *value;
- } PrivateCallbackRec;
-
- int dixRegisterPrivateInitFunc(const DevPrivateKey key,
- CallbackProcPtr callback,
- pointer userdata)
- int dixRegisterPrivateDeleteFunc(const DevPrivateKey key,
- CallbackProcPtr callback,
- pointer userdata)
-</programlisting></blockquote>
-The first argument is the key for which the callbacks are being registered. The second argument is the callback function. The third argument
-will be passed as the user data argument to the callback function when it is called. The call data argument to the callback is a pointer to
-a structure of type <type>PrivateCallbackRec</type>.</para>
-<para>
-The init callback is called immediately after new private space has been allocated for the given key. The delete callback is called immediately
-before the private space is freed when the object is being destroyed. The <type>PrivateCallbackRec</type> structure contains the devPrivate key
-and the address of the private pointer. The init callback may be used to initialize any pre-allocated space requested by
-<function>dixRequestPrivate</function>, while the delete callback may be used to free any data stored there. However the callbacks are called even
-if no pre-allocated space was requested.</para>
-
-<para>
-When implementing new server resource objects that support devPrivates, there are three steps to perform:
-Declare a field of type <type>PrivateRec *</type> in your structure;
+in the target structure. The second argument is the key to look up.
+If a non-zero size was given when the key was registered, or if private data
+with the given key is already associated with the object, then
+<function>dixLookupPrivate</function> will return the pointer value
+while <function>dixLookupPrivateAddr</function>
+will return the address of the pointer.</para>
+
+<para>
+When implementing new server resource objects that support devPrivates, there
+are four steps to perform:
+Add a type value to the <type>DevPrivateType</type> enum in
+<filename class="headerfile">Xserver/include/privates.h</filename>,
+declare a field of type <type>PrivateRec *</type> in your structure;
initialize this field to <literal>NULL</literal> when creating any objects; and
-call the <function>dixFreePrivates</function> function, passing in the field value, when freeing any objects.</para>
+when freeing any objects call the <function>dixFreePrivates</function> or
+<function>dixFreeObjectWithPrivates</function> function.</para>
</section>
<section>
<title>Wrappers</title>
commit 40d598a4f84091db743ceef4d60752bb910c3e56
Author: Alan Coopersmith <alan.coopersmith at oracle.com>
Date: Thu Jul 22 23:57:02 2010 -0700
Correct function name in dixRegisterPrivateKey comments
Signed-off-by: Alan Coopersmith <alan.coopersmith at oracle.com>
Reviewed-by: Patrick E. Kane <pekane52 at gmail.com>
diff --git a/include/privates.h b/include/privates.h
index 5ba9358..d3c0e13 100644
--- a/include/privates.h
+++ b/include/privates.h
@@ -81,10 +81,10 @@ typedef struct _DevPrivateKeyRec {
* you can get the address of the extra space and store whatever data you like
* there.
*
- * You may call dixRegisterPrivate more than once on the same key, but the
+ * You may call dixRegisterPrivateKey more than once on the same key, but the
* size and type must match or the server will abort.
*
- * dixRegisterPrivateIndex returns FALSE if it fails to allocate memory
+ * dixRegisterPrivateKey returns FALSE if it fails to allocate memory
* during its operation.
*/
extern _X_EXPORT Bool
More information about the xorg-commit
mailing list