From d2758df0a0091496717fe7a65c3e7563e7c82785 Mon Sep 17 00:00:00 2001 From: marha Date: Mon, 2 Aug 2010 08:29:58 +0000 Subject: xserver libX11 libXdmcp git update 2-8-2010 --- xorg-server/doc/xml/Makefile.am | 2 + xorg-server/doc/xml/Xserver-spec.xml | 8 +- xorg-server/doc/xml/dtrace/Makefile.am | 36 ++ xorg-server/doc/xml/dtrace/Xserver-DTrace.xml | 579 ++++++++++++++++++++++++++ xorg-server/doc/xml/xmlrules.in | 10 +- 5 files changed, 632 insertions(+), 3 deletions(-) create mode 100644 xorg-server/doc/xml/dtrace/Makefile.am create mode 100644 xorg-server/doc/xml/dtrace/Xserver-DTrace.xml (limited to 'xorg-server/doc/xml') diff --git a/xorg-server/doc/xml/Makefile.am b/xorg-server/doc/xml/Makefile.am index 3eba24e8c..2913eff55 100644 --- a/xorg-server/doc/xml/Makefile.am +++ b/xorg-server/doc/xml/Makefile.am @@ -21,6 +21,8 @@ # DEALINGS IN THE SOFTWARE. # +SUBDIRS = dtrace + XML_FILES = Xserver-spec.xml include xmlrules.in diff --git a/xorg-server/doc/xml/Xserver-spec.xml b/xorg-server/doc/xml/Xserver-spec.xml index 7249d4267..a457063bd 100644 --- a/xorg-server/doc/xml/Xserver-spec.xml +++ b/xorg-server/doc/xml/Xserver-spec.xml @@ -357,11 +357,15 @@ Resource types are integer values starting at 1. Get a resource type by calling
- RESTYPE CreateNewResourceType(deleteFunc) + RESTYPE CreateNewResourceType(deleteFunc, char *name)
deleteFunc will be called to destroy all resources with this -type. +type. name will be used to identify this type of resource +to clients using the X-Resource extension, to security +extensions such as SELinux, and to tracing frameworks such as DTrace. +[The name argument was added in xorg-server 1.8.] + Resource classes are masks starting at 1 << 31 which can be or'ed with any resource type to provide attributes for the diff --git a/xorg-server/doc/xml/dtrace/Makefile.am b/xorg-server/doc/xml/dtrace/Makefile.am new file mode 100644 index 000000000..946fba7d8 --- /dev/null +++ b/xorg-server/doc/xml/dtrace/Makefile.am @@ -0,0 +1,36 @@ +# +# Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved. +# +# Permission is hereby granted, free of charge, to any person obtaining a +# copy of this software and associated documentation files (the "Software"), +# to deal in the Software without restriction, including without limitation +# the rights to use, copy, modify, merge, publish, distribute, sublicense, +# and/or sell copies of the Software, and to permit persons to whom the +# Software is furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice (including the next +# paragraph) shall be included in all copies or substantial portions of the +# Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +# DEALINGS IN THE SOFTWARE. +# + +XML_FILES = Xserver-DTrace.xml + +include ../xmlrules.in + +if XSERVER_DTRACE +doc_DATA = $(BUILT_DOC_FILES) +else +noinst_DATA = $(BUILT_DOC_FILES) +endif + +CLEANFILES = $(CLEAN_DOC_FILES) + +EXTRA_DIST = $(XML_FILES) diff --git a/xorg-server/doc/xml/dtrace/Xserver-DTrace.xml b/xorg-server/doc/xml/dtrace/Xserver-DTrace.xml new file mode 100644 index 000000000..e0425c8ee --- /dev/null +++ b/xorg-server/doc/xml/dtrace/Xserver-DTrace.xml @@ -0,0 +1,579 @@ + + %defs; +]> + +
+ + Xserver provider for DTrace + + AlanCoopersmith + + Oracle Corporation + Solaris Engineering + + + X.Org Xserver version &xserver.version; + + +Copyright (c) 2005, 2006, 2007, 2010, Oracle and/or its affiliates. +All rights reserved. + +Permission is hereby granted, free of charge, to any person obtaining a +copy of this software and associated documentation files (the "Software"), +to deal in the Software without restriction, including without limitation +the rights to use, copy, modify, merge, publish, distribute, sublicense, +and/or sell copies of the Software, and to permit persons to whom the +Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice (including the next +paragraph) shall be included in all copies or substantial portions of the +Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + + + + + + Introduction + + This page provides details on a + statically defined user application tracing provider + for the + DTrace + facility in Solaris 10, + MacOS X 10.5, and later releases. This + provider instruments various points in the X server, to allow + tracing what client applications are up to. + + + + The provider was integrated into the X.Org git master repository + with Solaris 10 & OpenSolaris support for the Xserver 1.4 release, + released in 2007 with X11R7.3. Support for DTrace on MacOS X + was added in Xserver 1.7. + + + + These probes expose the request and reply structure of the X protocol + between clients and the X server, so an understanding of that basic + nature will aid in learning how to use these probes. + + + + + Available probes + + + Due to the way User-Defined DTrace probes work, arguments to + these probes all bear undistinguished names of + arg0, arg1, + arg2, etc. These tables should help you + determine what the real data is for each of the probe arguments. + + + Probes and their arguments + + + + + + + + + + + + Probe name + Description + arg0 + arg1 + arg2 + arg3 + arg4 + + + + + Request Probes + + + request-start + Called just before processing each client request. + requestName + requestCode + requestLength + clientId + requestBuffer + + + request-done + Called just after processing each client request. + requestName + requestCode + sequenceNumber + clientId + resultCode + + + Event Probes + + + send-event + Called just before send each event to a client. + clientId + eventCode + eventBuffer + + + + Client Connection Probes + + + client-connect + Called when a new connection is opened from a client + clientId + clientFD + + + + client-auth + Called when client authenticates (normally just after connection opened) + clientId + clientAddr + clientPid + clientZoneId + + + + client-disconnect + Called when a client connection is closed + clientId + + + + Resource Allocation Probes + + + resource-alloc + Called when a new resource (pixmap, gc, colormap, etc.) is allocated + resourceId + resourceTypeId + resourceValue + resourceTypeName + + + + resource-free + Called when a resource is freed + resourceId + resourceTypeId + resourceValue + resourceTypeName + + + + +
+ + + + + Data Available in Probe Arguments + + + To access data in arguments of type string, you will need + to use copyinstr(). + To access data buffers referenced via uintptr_t's, you will + need to use copyin(). + + + Probe Arguments + + + + + + + Argument name + Type + Description + + + + + clientAddr + string + String representing address client connected from + + + clientFD + int + X server's file descriptor for server side of each connection + + + clientId + int + Unique integer identifier for each connection to the + X server + + + clientPid + pid_t + Process id of client, if connection is local + (from getpeerucred()) + + + clientZoneId + zoneid_t + Solaris: Zone id of client, if connection is local + (from getpeerucred()) + + + eventBuffer + uintptr_t + Pointer to buffer containing X event - decode using + structures in + <X11/Xproto.h> + and similar headers for each extension + + + eventCode + uint8_t + Event number of X event + + + resourceId + uint32_t + X resource id (XID) + + + resourceTypeId + uint32_t + Resource type id + + + resourceTypeName + string + String representing X resource type + ("PIXMAP", etc.) + + + resourceValue + uintptr_t + Pointer to data for X resource + + + resultCode + int + Integer code representing result status of request + + + requestBuffer + uintptr_t + Pointer to buffer containing X request - decode using + structures in + <X11/Xproto.h> + and similar headers for each extension + + + requestCode + uint8_t + Request number of X request or Extension + + + requestName + string + Name of X request or Extension + + + requestLength + uint16_t + Length of X request + + + sequenceNumber + uint32_t + Number of X request in in this connection + + + +
+ + + + + Examples + + + Counting requests by request name + + + This script simply increments a counter for each different request + made, and when you exit the script (such as by hitting + ControlC + ) prints the counts. + + +#!/usr/sbin/dtrace -s + +Xserver*:::request-start +{ + @counts[copyinstr(arg0)] = count(); +} + + + The output from a short run may appear as: + + QueryPointer 1 + CreatePixmap 2 + FreePixmap 2 + PutImage 2 + ChangeGC 10 + CopyArea 10 + CreateGC 14 + FreeGC 14 + RENDER 28 + SetClipRectangles 40 + + + + + This can be rewritten slightly to cache the string containing the name + of the request since it will be reused many times, instead of copying + it over and over from the kernel: + + +#!/usr/sbin/dtrace -s + +string Xrequest[uintptr_t]; + +Xserver*:::request-start +/Xrequest[arg0] == ""/ +{ + Xrequest[arg0] = copyinstr(arg0); +} + +Xserver*:::request-start +{ + @counts[Xrequest[arg0]] = count(); +} + + + + + + Get average CPU time per request + + This script records the CPU time used between the probes at + the start and end of each request and aggregates it per request type. + + +#!/usr/sbin/dtrace -s + +Xserver*:::request-start +{ + reqstart = vtimestamp; +} + +Xserver*:::request-done +{ + @times[copyinstr(arg0)] = avg(vtimestamp - reqstart); +} + + + The output from a sample run might look like: + + + ChangeGC 889 + MapWindow 907 + SetClipRectangles 1319 + PolyPoint 1413 + PolySegment 1434 + PolyRectangle 1828 + FreeCursor 1895 + FreeGC 1950 + CreateGC 2244 + FreePixmap 2246 + GetInputFocus 2249 + TranslateCoords 8508 + QueryTree 8846 + GetGeometry 9948 + CreatePixmap 12111 + AllowEvents 14090 + GrabServer 14791 + MIT-SCREEN-SAVER 16747 + ConfigureWindow 22917 + SetInputFocus 28521 + PutImage 240841 + + + + + + + Monitoring clients that connect and disconnect + + + This script simply prints information about each client that + connects or disconnects from the server while it is running. + Since the provider is specified as Xserver$1 instead + of Xserver* like previous examples, it won't monitor + all Xserver processes running on the machine, but instead expects + the process id of the X server to monitor to be specified as the + argument to the script. + + +#!/usr/sbin/dtrace -s + +Xserver$1:::client-connect +{ + printf("** Client Connect: id %d\n", arg0); +} + +Xserver$1:::client-auth +{ + printf("** Client auth'ed: id %d => %s pid %d\n", + arg0, copyinstr(arg1), arg2); +} + +Xserver$1:::client-disconnect +{ + printf("** Client Disconnect: id %d\n", arg0); +} + + + A sample run: + + +# ./foo.d 5790 +dtrace: script './foo.d' matched 4 probes +CPU ID FUNCTION:NAME + 0 15774 CloseDownClient:client-disconnect ** Client Disconnect: id 65 + + 2 15774 CloseDownClient:client-disconnect ** Client Disconnect: id 64 + + 0 15773 EstablishNewConnections:client-connect ** Client Connect: id 64 + + 0 15772 AuthAudit:client-auth ** Client auth'ed: id 64 => local host pid 2034 + + 0 15773 EstablishNewConnections:client-connect ** Client Connect: id 65 + + 0 15772 AuthAudit:client-auth ** Client auth'ed: id 65 => local host pid 2034 + + 0 15774 CloseDownClient:client-disconnect ** Client Disconnect: id 64 + + + + + + + + Monitoring clients creating Pixmaps + + + This script can be used to determine which clients are creating + pixmaps in the X server, printing information about each client + as it connects to help trace it back to the program on the other + end of the X connection. + + +#!/usr/sbin/dtrace -qs + +string Xrequest[uintptr_t]; +string Xrestype[uintptr_t]; + +Xserver$1:::request-start +/Xrequest[arg0] == ""/ +{ + Xrequest[arg0] = copyinstr(arg0); +} + +Xserver$1:::resource-alloc +/arg3 != 0 && Xrestype[arg3] == ""/ +{ + Xrestype[arg3] = copyinstr(arg3); +} + + +Xserver$1:::request-start +/Xrequest[arg0] == "X_CreatePixmap"/ +{ + printf("-> %s: client %d\n", Xrequest[arg0], arg3); +} + +Xserver$1:::request-done +/Xrequest[arg0] == "X_CreatePixmap"/ +{ + printf("<- %s: client %d\n", Xrequest[arg0], arg3); +} + +Xserver$1:::resource-alloc +/Xrestype[arg3] == "PIXMAP"/ +{ + printf("** Pixmap alloc: %08x\n", arg0); +} + + +Xserver$1:::resource-free +/Xrestype[arg3] == "PIXMAP"/ +{ + printf("** Pixmap free: %08x\n", arg0); +} + +Xserver$1:::client-connect +{ + printf("** Client Connect: id %d\n", arg0); +} + +Xserver$1:::client-auth +{ + printf("** Client auth'ed: id %d => %s pid %d\n", + arg0, copyinstr(arg1), arg2); +} + +Xserver$1:::client-disconnect +{ + printf("** Client Disconnect: id %d\n", arg0); +} + + + Sample output from a run of this script: + +** Client Connect: id 17 +** Client auth'ed: id 17 => local host pid 20273 +-> X_CreatePixmap: client 17 +** Pixmap alloc: 02200009 +<- X_CreatePixmap: client 17 +-> X_CreatePixmap: client 15 +** Pixmap alloc: 01e00180 +<- X_CreatePixmap: client 15 +-> X_CreatePixmap: client 15 +** Pixmap alloc: 01e00181 +<- X_CreatePixmap: client 15 +-> X_CreatePixmap: client 14 +** Pixmap alloc: 01c004c8 +<- X_CreatePixmap: client 14 +** Pixmap free: 02200009 +** Client Disconnect: id 17 +** Pixmap free: 01e00180 +** Pixmap free: 01e00181 + + + + + + + + + +
+ diff --git a/xorg-server/doc/xml/xmlrules.in b/xorg-server/doc/xml/xmlrules.in index 1db7f128e..667cc2ebb 100644 --- a/xorg-server/doc/xml/xmlrules.in +++ b/xorg-server/doc/xml/xmlrules.in @@ -39,6 +39,14 @@ SUFFIXES = .xml .txt .html .pdf XML_ENT_DIR = $(abs_top_builddir)/doc/xml XMLTO_FLAGS = --searchpath $(XML_ENT_DIR) +if HAVE_STYLESHEETS +XMLTO_FLAGS += -m $(XSL_STYLESHEET) +BUILT_DOC_FILES += xorg.css + +xorg.css: $(STYLESHEET_SRCDIR)/xorg.css + $(AM_V_GEN)cp -pf $(STYLESHEET_SRCDIR)/xorg.css $@ +endif + if HAVE_XMLTO BUILT_DOC_FILES += $(TXT_FILES) .xml.txt: @@ -59,7 +67,7 @@ endif endif -CLEAN_DOC_FILES = $(TXT_FILES) $(HTML_FILES) $(PDF_FILES) +CLEAN_DOC_FILES = $(TXT_FILES) $(HTML_FILES) $(PDF_FILES) xorg.css # All the files we build depend on the entities $(BUILT_DOC_FILES): $(XML_ENT_DIR)/xserver.ent -- cgit v1.2.3