XGE protocol spec

[Jim Gettys]

A couple comments below.

On Mon, 2008-12-01 at 16:15 +1000, Peter Hutterer wrote:
> Below is the protocol spec for the X Generic Event Extension (XGE). It'll be
> shipped with 1.6 even though there won't be any consumers for it yet.
> (This is the current proto/xextproto/geproto.txt file as valid in my tree. Will
> be pushed pending no objections.)
> 
> Cheers,
>   Peter
> 
>                          X Generic Event Extension
>                               Peter Hutterer
>                           peter.hutterer at who-t.net
> 
> 
> 1. Introduction
> 2. Extension Initialization
> 3. Extension Events
> 4. Notes
> 
> _____________________________________________________________________________
> 1. Introduction
> 
> X was designed to provide 64 event opcodes for all extensions. These events
> are limited to 32 bytes.
> 
> The Generic Event Extension is a template for extensions to re-use a single
> event opcode. GE only provide headers and the most basic functionality,
> leaving the extensions to interpret the events in their specific context.
> 
> GenericEvents may be longer than 32 bytes. If so, the number of 4 byte units
> following the initial 32 bytes must be specified in the length field of the
> event.

1.1 History and Rationale

The original rationale for X11's fixed event size was that certain
platforms (notably VAX/VMS) had very poor malloc and free C library
implementations with terrible performance (both CPU and memory usage).
Malloc's memory usage with the then common Berkeley 4.2 allocator tended
to be profligate in space. By using a single event size both memory
fragmentation and performance problems were avoided. Retaining this
restriction on modern systems would continue to complicate X's evolution
and implementation unnecessarily.

> _____________________________________________________________________________
> 2. Extension Initialization
> 
> The name of this extension is "Generic Event Extension"
> 
> ┌───
>     GEQueryVersion
> 	client-major-version:	CARD16
> 	client-minor-version:	CARD16
>       ▶
> 	major-version:		CARD16
> 	minor-version:		CARD16
> └───
> 
> 	The client sends the highest supported version to the server
> 	and the server sends the highest version it supports, but no
> 	higher than the requested version. Major versions changes can
> 	introduce incompatibilities in existing functionality, minor
> 	version changes introduce only backward compatible changes.
> 	It is the clients responsibility to ensure that the server
> 	supports a version which is compatible with its expectations.
> 
> 
>         As of version 1.0, no other requests are provided by this extension.
> _____________________________________________________________________________
> 3. Extension Events
> 
> GE defines a single event, to be used by all extensions. The event's structure 
> is similar to a request.
> 
> ┌───
>     RRScreenChangeNotify
> 	type: BYTE;			always GenericEvent
> 	extension: CARD8;		extension offset
> 	sequenceNumber: CARD16		low 16 bits of request seq. number
> 	length: CARD32			time screen was changed
> 	evtype: CARD16			event type
> └───
> 

Do you really want to leave this only 16 bit aligned?  Would two bytes
of padding be wise here?  I suspect we do....

> 	The field 'extension' is to be set to the major opcode of the
> 	extension. The 'evtype' field is the actual opcode of the event. 
> 	The length field specifies the number of 4-byte blocks after the
> 	initial 32 bytes.
> 
> _____________________________________________________________________________
> 4. Notes
> 
> Although the wire event is of arbitrary length, the actual size of an XEvent
> is restricted to sizeof(XEvent) [96 bytes, see Xlib.h]. If an extension
> converts a wire event to an XEvent > 96 bytes, it will overwrite the space
> acllocated for the event. See struct _XSQEvent in Xlibint.h for details.
> 
> Extensions need to malloc additional data and fill the XEvent structure with
> pointers to the malloc'd data. The client then needs to free the data, only
> the XEvent structure will be released by Xlib.
> 
> The server must not send GenericEvents longer than 32 bytes until it has
> verified that the client is able to interpret these events. If a long event is
> sent to a client unable to process GenericEvents, future interpretation of
> replies and events by this client will fail.
> 
> _______________________________________________
> xorg mailing list
> xorg at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/xorg
-- 
Jim Gettys <jg at laptop.org>
One Laptop Per Child