
\documentstyle[twocolumn,psfig]{article}

\topmargin -0.1in
\headheight 0in
\headsep 0in
\oddsidemargin -.20in
\evensidemargin -.20in
\textwidth 7.1in
\textheight 9.2in

\begin{document}

\title{{\huge XamineYourZerver } \\
An X11 Extension for Server \\
Instrumentation and Tracing}
\author{Mark J. Kilgard 
\thanks{Mark is currently employed by Silicon Graphics Inc. and can be
reached by electronic mail addressed to {\tt mjk@sgi.com}}\\
{\em Compaq Computer Corp.}}

\maketitle

\begin{abstract}
This paper describes the design and implementation of an X11
server extension named XamineYourZerver 
used for server instrumentation and tracing.
Justification for the extension is supplied.
XamineYourZerver can be used to direct targeted
server optimization and to construct server
tests which verify that particular paths through the server
are exercised.
A client programming interface and the
extension protocol encoding are described
in appendixes.
\end{abstract}

\section{Introduction}

XamineYourZerver (or XYZ for short) is an X11 server extension
to allow programmers
involved in server development and testing to easily instrument
and trace X servers.  
Unlike most X11 protocol extensions, the XamineYourZerver extension is
designed not to increase X server functionality, but instead to aid
server developers in better understanding the behavior of their servers.

The XYZ extension allows server developers to
place {\em tags} in server routines which are counted
and/or traced each time they are executed.  Then an X client using
the XYZ extension can 
turn on or off counting or tracing of the tags;
query the counts for specified tags;
and set the value and trace level of tags.

The next section will examine the need for instrumentation
and tracing in general.  The third section will explain
the XYZ extension's intent and justify the use of a server extension
to realize this intent.  The fourth and fifth sections will respectively
describe the
functionality of the extension and its implementation.
The sixth section
will examine the applications 
of XYZ.  Two appendixes are provided detailing an XYZ client
programmer interface and the XYZ protocol in
standard X protocol encoding notation.

% this is a hack to get this section title to be ragged right
% without letting the first paragraph be indented!
{\raggedright
\section{The Need for Instrumentation and Tracing}

A } major challenge for programmers is to {\em get a handle on} the behavior
of complex programs.
Often this challenge is part
of finding and eliminating a bug.  In other instances, the challenge
is part of an effort to characterize program operation so routines can
be targeted for optimization.  Sometimes the challenge is part of
testing to verify that obscure execution paths are being taken and
indeed perform
correctly.

The phrase {\em get a handle on} is a sloppy way of saying that
the programmer needs a way of following the execution of a program
at the necessary level of detail to determine why a program
is performing as it does.

There are five common methods of achieving this end:

\begin{itemize}
\item Careful reading of code.
\item Interactive stepping through code with a debugger.
\item Profiling which involves measuring the time various operations take.
\item Instrumentation which is {\em counting} events
in the program.
\item Tracing which means outputting messages about the program's progress
as the program is executing.
\end{itemize}

Each of these methods have their own advantages and disadvantages.
For example, careful code reading can be very comprehensive, but
it often fails to expose subtle, dynamic workings of the code.  Also
it takes a large amount of time.
Interactive stepping through code with a debugger
gives the programmer a great deal of control and detail but is
often tedious because it requires the active involvement of
the programmer.  Profiling is very valuable for determining
real performance timings but many profiling methods suffer from
presenting too much poorly targeted  data; from the sampled nature of the data;
and from the need for specific termination points.

Where code reading, interactive debugging, and profiling are less
effective, instrumentation and tracing can fill in the gaps.  To
the advantage of instrumentation
and tracing, they require less interactive involvement during use.  
To their disadvantage, they require the program to be augmented
by statements to perform the instrumentation and tracing.  

When used, methods for instrumentation and tracing tend to be very {\em ad hoc}.
Tracing usually consists of scattering print statements through
the program source code.  Instrumentation usually means
introducing variables used to count events and the associated code
to do the counting.  When the tracing and instrumentation support
needs to be stripped out, this can often be error-prone leading
to unused variables, print statements left in, or possibly even
deletion of code not for instrumentation or tracing.

A system for performing program instrumentation and tracing 
designed to be easily disabled, portable, and highly functional
would be extremely desirable for X server developers and testers.
It would be even more desirable if it was accessible through
the same client-server mechanism other X services are made available.
XYZ is an implementation of such a system.

\section{XYZ's Intent}

The intent of the XYZ extension is to make the task of instrumenting
and tracing an X11 server less {\em ad hoc}.  There should be an easy,
standard way for a programmer to add instrumentation and tracing to
an X server.

\subsection{Requirements}

Beyond just making the process less {\em ad hoc}, other important
requirements should be established for the extension:
\begin{itemize}
\item The extension should be non-intrusive when used; use of the extension's facilities
should not change server behavior.
\item Understood in the idea of being an extension is the notion
that control of the facility should be through X clients.
\item The extension should be easy to disable.  Using conditional compilation,
a version of the 
server without XYZ support should be able to be built from the same
source tree as one with XYZ support.  
The extension should
be able to be wholely removed from the server without affecting server
operation.  
\item The extension should be non-intensive; the extension should not
unduly denigrate server performance when used.
\item The extension should be able to supply genuinely useful information
to the server implementor.
\item The extension should integrate the notion of instrumentation
and tracing.  A single mechanism should place tags in the code
and these tags should be usable by either method.
\end{itemize}
It is the explicit goal of XYZ to meet all of these requirements.

Implicit so far in our discussion is the idea that a server
extension is the right mechanism to provide server instrumentation
and tracing.
Before discussing the actual functionality of the XYZ extension,
some discussion should be presented for why a server extension
is an appropriate means to support X server instrumentation
and tracing.

As mentioned in the requirements, we want to be able to use
the facility through the client-server interface.  This is natural
because some interface to the facility will be necessary and the
client-server interface is readily available and network
accessible.  Additionally, providing access through the client-server
interface makes it easy to construct tests out of clients.

The facility might be able to be built on top of the current
properties mechanism to avoid implementing an extension.  This
mechanism was rejected because it places the instrumentation and tracing
data in a very public data-space.  Instead, it is preferable to
provide a private name-space for the instrumentation and tracing
data only accessible through an extension.

\subsection{Non-intent}

XYZ is {\em not} intended to be an X11 protocol viewer like
{\tt xscope}.  Tools like {\tt xscope} are quite useful but
do not reveal details internal to the server.  XYZ allows
X activity to be examined at a much lower level than allowed
by protocol viewers.
The focus of XYZ is on server internals, not protocol details.

\section{Extension Functionality}

XYZ manages a set of {\em tags}.  A tag consists of a tag name,
a tag value, and a trace level.  
The tag name is a character string used to name a specific
tag.  The tag value is a signed integer counter.  The trace level
is used to determine if a tag should be output if tracing
is enabled.

\begin{figure}[tb]
\begin{center}
{\tt
\begin{tabular}{|l|}
\hline
\\
int \\
ProcBadRequest(client) \\
\hspace{1.5em}ClientPtr client; \\
\{ \\
\hspace{1.5em}XYZ("ProcBadRequest-entered"); \\
\hspace{1.5em}return (BadRequest); \\
\} \\
\\
\hline
\end{tabular}
}
\end{center}
\caption{Example of use of {\tt XYZ} macro.}
\label{fig:xyz-example}
\end{figure}

Tags are used by scattering {\tt XYZ} macros through server
code intended to be instrumented or traced.  The {\tt XYZ} macro
takes a tag name as its single argument.  Figure \ref{fig:xyz-example} shows
an example code fragment which uses the {\tt XYZ} macro.  When the macro is
encountered during code execution, the macro either: 
\begin{enumerate}
\item increments
the tag value by one for the named tag,
i.e. instrumentation;  
\item outputs the tag name and corresponding tag value if the
trace level for the tag is less than or equal to the current
trace level, i.e. tracing; 
\item does both; or
\item does nothing.
\end{enumerate}
The {\em XYZ instrumentation} and {\em XYZ tracing} booleans determine
whether the instrumentation and tracing functions are enabled or not.

The outcome also depends on the {\em XYZ status} which can be either
{\tt XYZ\_NO\_ERROR} (the normal state) or {\tt XYZ\_ERROR}.  If the
XYZ status is {\tt XYZ\_ERROR}, the incrementing of the tag value is
not performed.  When the XYZ status is reset to {\tt XYZ\_NO\_ERROR},
the instrumentation function will resume.

Because the instrumentation function can cause memory to be dynamically
allocated (an operation which can fail), the {\tt XYZ\_ERROR} status
is used to signal failure.  The stopping of instrumentation results
in predictable semantics in the face of memory allocation failure.

In the tracing case, whether the tag name and tag value are
actually output or not depends on the trace level for that tag.
By default, all tag trace levels are 255.  XYZ maintains a
{\em current trace level}.  
If the trace level of the specified
tag is less than or equal to the current trace level, the
tag is output.  Individual trace levels of tags can be changed
using XYZ requests.

A version of the {\tt XYZ} macro called {\tt XYZdelta} is also
available which takes a second signed integer argument which
is the amount to change the tag value by for the named tag.

\subsection{The XYZ State}

This means that XYZ maintains the following abstract state:
\begin{description}
\item[\em tag space] - consisting of tags which are mappings from a
tag name to a tag value and tag trace level.  Only one mapping
exists per tag name.  Mappings exist for all possible tag names.
\item[\em current trace level] - being an integer in the range
of 0 to 255 inclusive.
\item[\em XYZ instrumentation] - a boolean, true denoting instrumentation is on.
\item[\em XYZ tracing] - a boolean, true denoting tracing is on.
\item[\em XYZ status] - also discussed above.
\end{description}
It is important to note that the tag
space is defined for all tag names, but unless otherwise
set or modified, the value of any tag is zero and its trace level
is 255.

The initial state is for
the XYZ mode to be {\em off}, the XYZ status
to be {\em no error}, and the current trace level to be 255.  
An implementation may use command line arguments to change these initial
defaults.

The state of the tag space is {\em not} reset on each server
generation.  

\subsection{The Requests}

The XYZ extension consists of ten new requests and no new errors
or events.  The actual protocol encoding for XYZ can be found in Appendix B.
The requests are of two types:
\begin{enumerate}
\item those requests used to set or query the state of the XYZ facility
exclusive of the tag space, i.e. the state used to
determine XYZ's operation; and
\item those requests used to set or query the state of the tag space.
\end{enumerate}

The first category consists of four requests.

{\bf XamineYourZerverInstrumentation} is used to turn on or off
XYZ's instrumentation function.
The request also has the side effect of resetting
the XYZ status to the {\em no error} state ({\tt XYZ\_NO\_ERROR}).  The
request has no reply.

{\bf XamineYourZerverTracing} is used to turn on or off XYZ's
tracing function.  The request has no reply.

{\bf XamineYourZerverSetCurTraceLevel} is used to change the current
trace level.  The request does not actually enable tracing;
that is done through the previous request.  The request has no
reply.

{\bf XamineYourZerverQueryState} is used to query the XYZ status,
current trace level, and the XYZ instrumentation
and tracing booleans.  The information is returned
by a reply.

The second category of requests used to query or modify the tag space
consists of six requests.

{\bf XamineYourZerverGetTag} is used to query the value and
trace level of a specific tag named in the request.  The reply
contains the value and trace level.

{\bf XamineYourZerverSetValue} is used to set the value of a
specific tag named in the request to a specified value.  This
request has no reply.

{\bf XamineYourZerverSetTraceLevel} is used to set the trace level
of a specific tag named in the request to a trace level specified
in the request.  This request has no reply.

{\bf XamineYourZerverListValues} is used to obtain the values
of tags whose tag names match any of a set of patterns supplied
by the request  and whose tag value is {\em not} zero.
The patterns should use the ISO Latin-1 encoding.  In each pattern,
the ``?'' character will match any single character,
and the ``*'' character will match any number of characters.
Patterns are case sensitive.
The maximum numbers of tags to be returned must be specified.
The reply consists of tag name and tag value
pairs, the number of matching tags, and the number of matching
pairs actually returned. 

Implicit in the idea of matching 
patterns is the idea that tag names have been
selected to make pattern matching an effective way of specifying
sets of tags.  For example, a server implementor
might suffix all tag names of tags at function entry points
with ``{\tt -entered}'' so he could search for ``{\tt $*$-entered}''
and query the tag values for all tagged function entry points.
The extension itself defines no conventions for tag naming.

{\bf XamineYourZerverResetValues} is used to reset
all tags in the tag space to the default value of zero.
The request also has the side effect of resetting
the XYZ status to the {\em no error} state.  The
request has no reply.

{\bf XamineYourZerverResetTraceLevels} is used to reset
all trace levels in the tag space to the default value of 255.
The request also has the side effect of resetting
the XYZ status to the {\em no error} state.  The
request has no reply.

\subsection{Design Issues}

The number of available requests have been kept small to minimize
the extension complexity.  The lack of events or errors is
also to minimize extension complexity.

The extension can be used by any X client authorized to connect
to an XYZ-capable server.  There is the potential for multiple clients to
interleave XYZ requests and make the use of XYZ confusing.
Since the extension is intended only for the limited application
of server instrumentation and tracing, this is not deemed a
problem.  The extension was designed under the assumption that
a single XYZ client would be used to monitor the server via
the XYZ facility.

\section{XYZ's Implementation}

The XYZ server extension implementation by the author 
is designed to be easily portable
to X11 server implementations based on MIT's X11 distributions.
The server-side and client-side code should be able to be {\em
dropped in} any X11R4 or X11R5 derived server and/or X extension
library.

The server code for the extension is implemented to use
a standard bucket hash table for managing the tag space.
Tags not found in the hash table are assumed to have the default
value of zero and trace level of 255.

The main performance issue for XYZ is the execution speed of the
{\tt XYZ} macro.  If the macro is too expensive, server implementors
will shy from using the XYZ facility.  

In particular, the execution
of the {\tt XYZ} macro should only perform a hash table look up
on named tag name if it has not already done so.  Each instance of
the {\tt XYZ} macro maintains static state (a small structure) used for this
purpose.  If the static state does not already contain a reference
to the named tag, a hash table look up will be performed and the
static state will be updated to contain a reference to the named tag.
Then subsequent calls can use the previously looked up tag reference.
Note that entries in
the hash table can be removed.  In this case,
XYZ must invalidate all the {\em cached} static look ups for the tag
being removed.

The implemented
client programmers interface for XYZ is described in Appendix A.
The author has implemented the interface on top of the Xlib library.

A disadvantage of this approach is that IO errors
due to the lost of a server connection are nearly impossible
to recover from in the current Xlib architecture.  (The
{\tt XSetIOErrorHandler} function allows for detection but not
adequate opportunity for recovery.)
This means if
a server crashes which is being monitored by a client using XYZ, the XYZ
client is forced to terminate as a result of the lost connection.
The XYZ client programmer interface could be reimplemented to avoid
this difficulty and probably will be in the future.

Also because the current XYZ client library is implemented on top
of Xlib, XYZ client programmers will want to override the client-side
buffering
Xlib provides by default.  XYZ requests
tend to demand immediate execution therefore buffering is not desirable.
The Xlib {\tt XSynchronize} function should be used to turn off buffering
for an XYZ display connection.

\section{XYZ Applications}

\begin{figure}[tb]
\centerline{\psfig{figure=xyztool.eps,width=3.3in}}
\caption{Sample {\tt xyztool} screen.}
\label{xyztool-screen}
\end{figure}

The intended application of XYZ is to allow server developers and testers
to better debug, optimize, and test X servers.  Experience may also
show
XYZ is also very useful to
the client programmer interested in knowing what is happening inside the
X server when a given client is running.

The most important factor in XYZ's utility is
how many and how well placed and named the {\tt XYZ}
macros are in the server code.  XYZ will be of little value if the
necessary tags are not in the server code.

The author's experience is that every X request procedure, the memory
allocation routines, and code around the {\tt select} system call
are all very good places to place tags.  The best way to achieve
a well tagged server is to place tags in these location and
then place additional tags in code that is being modified or added.

It is
also very important to have a set of tag naming conventions that are
used and adhered to.  This makes the pattern matching functionality
of the {\bf XamineYourZerverListValues} request much more useful.

\subsection{XYZ Clients}

After having a well tagged server, the next most critical
component to using  XYZ effectively is having
a set of clients that use the extension.
The author has implemented two clients which make use of XYZ.

The first
is a utility called {\tt xyz} which allows individual XYZ requests to
be performed.  Command line options or standard input can be used
to invoke XYZ requests.  The {\tt xyz} command is intended to be placed
into test scripts.

The second client has a graphical user interface (pictured in Figure
\ref{xyztool-screen}) and is called {\tt xyztool}.  The GUI for
{\tt xyztool} is X based and allows the user to connect to an XYZ-capable
X server (not necessarily the one that {\tt xyztool} is displaying to)
and perform XYZ querys and requests.

{\tt xyztool} allows a user to very quickly interact with XYZ and query
exactly the tag values that are interesting.  It allows the tool to
periodically poll the server at regular intervals.  The tag values
can be shown as absolute values or as the difference from the
previous values.

These two clients provide a versatile means of interaction
with XYZ to better enable their users to
understand what is happening in a server.

\subsection{Optimization Applications}

The key to good server optimization is targeting your optimization effort
so effort spent on optimization will be truly reflected in overall
server performance.  It would be a shame to waste time optimizing something
like dash wide arcs if 99\% of the clients written will never even use
this rendering request.  XYZ can be extremely useful in this targeting
process.

Examining the tag counts of a server with {\tt xyztool} under normal
use quickly lets a developer determine what code is being well exercised.
Also, tags can be placed in routines specifically to detect how
often a certain optimizable special case is occurring.  Using XYZ,
the decision of whether or not to expend the effort to exploit
that special case can be made on a well-founded empirical basis.

A case the author found XYZ extremely useful was tuning a glyph
caching algorithm developed for Compaq's QVision X server driver.  Glyph
caching is a specialized server optimization
to improve text performance.  
It stores often used glyphs in
off-screen frame buffer memory and then uses a hardware blit engine to
quickly copy the glyphs onto the screen in the proper location.
Glyph caching involves properly managing the off-screen memory
so glyphs can be effectively cached.

XYZ proved itself quite useful in tuning the hash table and other
glyph caching data structures.  Verification of the effectiveness
of the victim glyph selection policy (the policy that determines
when glyphs should be kicked out off-screen memory) was
done with XYZ.

Like any caching technique, good tuning
is important otherwise, the overhead of caching could lead to
a performance degradation.

\subsection{Testing Applications}

In a well tuned X server, often many paths through the code
are possible given various special cases. 

Often the more work that is spent optimizing a server, the more
these paths proliferate.  Examples of such paths might be
fast code to handle the case of a single clipping rectangle,
drawing on aligned word boundaries, and blits for fast drawing
of circles of small radii.
It becomes difficult to test that
a particular path remains correct because clients used to test
server correctness are generally ignorant of the internal
server implementation.  For this reason, it is quite difficult
to ensure testing coverage of all paths through server
algorithms.

The XYZ extension can be used to remedy this situation.  By
carefully placing {\tt XYZ} macros down each path of the
algorithm to be tested, a client using XYZ can query the
server to check what paths through the algorithm are being hit.

Realize such testing does require the test (or at least the
tester) to be aware of what tag names are in the server.
Careful construction of {\em internals aware} tests can
ensure testing really exercises critical server algorithms.

In the glyph caching example cited earlier, testing using XYZ
verified that rare conditions were indeed being executed correctly.

\subsection{Debugging Applications}

Because XYZ can report what is going on inside the server, it is
also appropriate for server debugging.  For example, if a client
exposes a rendering bug, {\tt xyztool} could be used to see what
rendering requests were performed when the bug was exposed.

The tracing functionality can also be used to track the flow of
control through the server to expose bugs.  But the author's experience is that
the tracing functionality of XYZ has not been very useful.  It
is tedious to mask out the many unimportant tracing messages and
requires careful examination of the trace to determine what happened.

Tracing remains a part of XYZ because it is cheap to add and may be
beneficial for some uses.

\section{Conclusion}

XamineYourZerver promises to be a valuable tool for learning more
about the operation of X11 servers.  It certainly makes the process
of adding instrumentation and tracing to an X server less {\em ad hoc}.
The goals of allowing a client-accessible interface, being easy to disable,
non-intrusive, non-intensive, and tying together tracing and
instrumentation functionality are all met by XYZ. 

The XamineYourZerver extension has been implemented and used in
conjunction with the development of an X11R4 server for Compaq's
prototype MIPS workstation which uses graphics hardware identical
to the REX hardware in the Indigo workstation manufactured by
Silicon Graphics.  The extension has also been ported to the SCO
Unix server and the Silicon Graphics IRIX server.

\appendix

\raggedbottom

\section{XYZ Client PI}

The following describes the XYZ client
programming interface which consists of
a set of routines for accessing the XYZ
extension.  These routines
are intended to be included as part of the X Extension Library (Xext).
The C language binding is described.
These interfaces have been implemented.

The routines returning {\tt Status} return
one if successful; zero otherwise.

\begin{verbatim}
Bool
XYZ_QueryExtension(
   Display *dpy);
\end{verbatim}

Returns true if the specified display supports the XYZ extension;
false otherwise.

\begin{verbatim}
Status
XYZ_Instrument(
   Display *dpy,
   int instrument);
\end{verbatim}

Turns on or off instrumentation.
It has a side effect of resetting the error status of XYZ to {\em no error}.

\begin{verbatim}
Status
XYZ_Trace(
   Display *dpy,
   int instrument);
\end{verbatim}

Turns on or off tracing.

\begin{verbatim}
Status
XYZ_SetCurTraceLevel(
   Display *dpy,
   int tracelevel);
\end{verbatim}

Sets the trace level of XYZ to the specified level.  This does not
affect whether tracing is turned on or off.

\begin{verbatim}
Status
XYZ_QueryState(
   Display *dpy,
   int *instrument;
   int *trace;
   int *tracelevel,
   int *status);
\end{verbatim}

Returns the XYZ trace and instrument booleans, the current
trace level, and status of XYZ.

\begin{verbatim}
Status
XYZ_GetTag(
   Display *dpy,
   char *tagname,
   int *value,
   int *tracelevel);
\end{verbatim}

Given a tag name, returns the tag's value.  If the execution server has not
encountered the tag, the value returned is zero.

\begin{verbatim}
Status
XYZ_SetValue(
   Display *dpy,
   char *tagname,
   int value);
\end{verbatim}

Given a tag name, sets the tag value to the given value.

\begin{verbatim}
Status
XYZ_SetTraceLevel(
   Display *dpy,
   char *tagname,
   int tracelevel);
\end{verbatim}

Given a tag name, sets the tag trace level to the given trace level.

\begin{verbatim}
struct _XYZ_value {
   char *tagname;
   int value;
} XYZ_value;
\end{verbatim}

\begin{verbatim}
XYZ_value *
XYZ_ListValues(
   Display *dpy,
   int numpat;
   char **pattern,
   int *patlens,
   int maxtags,
   int *total,
   int *returned);
\end{verbatim}

Given a number of patterns, this routine returns the name/value pairs for all
tags whose name matches at least one of the patterns {\em and} and
whose value is not zero.
The patterns are specified by {\tt pattern} which is an array of
{\tt numpat}
character strings.  The {\tt patlens} parameter is an array of
{\tt numpat} integers specifying the length of each pattern string.
Up to a maximum
of {\tt maxtags} tags are returned.  On completion,
the value pointed to by {\tt returned} 
is updated to be the number of tags returned.
The value pointed to by {\tt total} is updated to be the number of tags
whose value is not zero that matched at least one of the patterns.
This may be greater
than the number of tags returned.
The return value is an array of type {\tt XYZ\_value} which contains
the data about the matching tag names and values.  If no matches
are found, {\tt NULL} is returned.  Memory for the
array is dynamically allocated.   If the memory allocation fails,
{\tt NULL} is returned {\em and} the values pointed to by
{\tt total} and {\tt returned} are set to negative one.

\begin{verbatim}
void
XYZ_FreeValueList(
   XYZ_value *values_list);
\end{verbatim}

Used to free an array (including data pointed to in the array)
allocated using {\tt XamineYourZerverListValues}.

\begin{verbatim}
Status
XYZ_ResetValues(
   Display *dpy);
\end{verbatim}

Resets all values of all tags for the display to zero.
It has a side effect of resetting the error status of XYZ to {\em no error}.

\begin{verbatim}
Status
XYZ_ResetTraceLevels(
   Display *dpy);
\end{verbatim}

Reset all trace levels of all tags for the display to the
default trace level, 255.
It has a side effect of resetting the error status of XYZ to {\em no error}.

\section{Protocol Encoding}

Please refer to the X11 Protocol Reference Manual as this appendix uses
conventions established there.
``{\tt XamineYourZerver}'' is the name of the extension.

\vspace{.5cm}

{\large \bf New types}

\vspace{.2cm}

{\bf TAG}

\nopagebreak

\begin{tabular}{l|l|l}
2 & n & length of tag name \\
n & STRING8 & tag name \\
p & & unused, p = pad(2+n) \\
4 & INT32 & value \\
\end{tabular}

\vspace{.2cm}

{\bf PATTERN}

\nopagebreak

\begin{tabular}{l|l|l}
2 & CARD16 & length \\
n & STRING8 & pattern \\
p & & unused, p = pad(2+n) \\
\end{tabular}

\vspace{.2cm}

{\bf XYZSTATUS}

\nopagebreak

\begin{tabular}{l|l}
0 & XYZ\_NO\_ERROR \\
1 & XYZ\_ERROR \\
\end{tabular}

\vspace{.5cm}

{\large \bf Requests}

\nopagebreak

\vspace{.2cm}

\nopagebreak

{\bf XamineYourZerverInstrumentation}

\nopagebreak

\begin{tabular}{l|l|l}
1 & CARD8 & extension opcode \\
1 & 0 & xyz opcode \\
2 & 2 & request length \\
1 & BOOL & on or off \\
3 & & pad \\
\end{tabular}

\vspace{.2cm}

{\bf XamineYourZerverTracing}

\nopagebreak

\begin{tabular}{l|l|l}
1 & CARD8 & extension opcode \\
1 & 1 & xyz opcode \\
2 & 3 & request length \\
1 & BOOL & on or off \\
3 & & pad \\
\end{tabular}

\vspace{.2cm}

{\bf XamineYourZerverSetCurTraceLevel}

\nopagebreak

\begin{tabular}{l|l|l}
1 & CARD8 & extension opcode \\
1 & 2 & xyz opcode \\
2 & 2 & request length \\
1 & CARD8 & trace level \\
3 & & pad \\
\end{tabular}

\vspace{.2cm}

{\bf XamineYourZerverQueryState}

\nopagebreak

\begin{tabular}{l|l|l}
1 & CARD8 & extension opcode \\
1 & 3 & xyz opcode \\
2 & 1 & request length \\
\multicolumn{3}{l}{$=>$} \\
1 & 1 & Reply \\
1 & & pad \\
2 & CARD16 & sequence number \\
4 & 0 & length \\
1 & CARD8 & trace level \\
1 & XYZSTATUS & status \\
1 & BOOL & instrumentation \\
1 & BOOL & tracing \\
20 & & unused \\
\end{tabular}

\vspace{.2cm}

{\bf XamineYourZerverGetTag}

\nopagebreak

\begin{tabular}{l|l|l}
1 & CARD8 & extension opcode \\
1 & 4 & xyz opcode \\
2 & 2+(n+p)/4 & request length \\
2 & n & length of tag name \\
2 & & pad \\
n & STRING8 & tag name \\
p & & unused, p = pad(n) \\
\multicolumn{3}{l}{$=>$} \\
1 & 1 & Reply \\
1 & CARD8 & trace level \\
2 & CARD16 & sequence number \\
4 & 0 & length \\
4 & INT32 & value \\
20 & & unused \\
\end{tabular}

\vspace{.2cm}

{\bf XamineYourZerverSetValue}

\nopagebreak

\begin{tabular}{l|l|l}
1 & CARD8 & extension opcode \\
1 & 5 & xyz opcode \\
2 & 3+(n+p)/4 & request length \\
4 & INT32 & tag value \\
2 & n & length of tag name \\
2 & & pad \\
n & STRING8 & tag name \\
p & & unused, p = pad(2+n) \\
\end{tabular}

\vspace{.2cm}

{\bf XamineYourZerverSetTraceLevel}

\nopagebreak

\begin{tabular}{l|l|l}
1 & CARD8 & extension opcode \\
1 & 6 & xyz opcode \\
2 & 2+(n+p)/4 & request length \\
1 & CARD8 & trace level \\
1 & & pad \\
2 & n & length of tag name \\
n & STRING8 & tag name \\
p & & unused, p = pad(3+n) \\
\end{tabular}

\vspace{.2cm}

{\bf XamineYourZerverListValues} 

\nopagebreak

\begin{tabular}{l|l|l}
1 & CARD8 & extension opcode \\
1 & 7 & xyz opcode \\
2 & 2+n/4  & request length \\
2 & CARD16 & number of patterns \\
2 & CARD16 & maximum \\
  & & number of tags \\
n & LISTofPATTERN & pattern \\
\multicolumn{3}{l}{$=>$} \\
1 & 1 & Reply \\
1 & & pad  \\
2 & CARD16 & sequence number \\
4 & n/4 & length \\
2 & CARD16 & returned \\
2 & CARD16 & total \\
20 & & pad \\
n & LISTofTAG & tags \\
\end{tabular}

\vspace{.2cm}

{\bf XamineYourZerverResetValues}

\nopagebreak

\begin{tabular}{l|l|l}
1 & CARD8 & extension opcode \\
1 & 8 & xyz opcode \\
2 & 1 & request length \\
\end{tabular}

\vspace{.2cm}

{\bf XamineYourZerverResetTraceLevels}

\nopagebreak

\begin{tabular}{l|l|l}
1 & CARD8 & extension opcode \\
1 & 9 & xyz opcode \\
2 & 1 & request length \\
\end{tabular}

\end{document}

