[Xcb] XCB-XML: Specification for alignments?

Sun Nov 7 16:04:28 PST 2010

Hello, 

this is my proposal for the alignment padding. For the purposes of
present proposal I introduce a new contruct

<sizeof>reference</sizeof>, 

which references to a name of entity (list or field) and giving a size
in bytes of this entity. <sizeof> helps to avoid duplication of the
complex expressions for length of lists.

Example 1. Simple length expression.

<list type="char" name="vendor">
  <fieldref>vendor_len</fieldref>
</list>

<sizeof>vendor</sizeof> is a size in bytes of list "vendor"; in this
simple case it will be equal to "vendor_len".

Example 2. Complex length expression.

<list type="void" name="data">
  <op op="/">
    <op op="*">
      <fieldref>data_len</fieldref>
      <fieldref>format</fieldref>
    </op>
    <value>8</value>
  </op>
</list>

<sizeof>data</sizeof> references to the length expression
"data_len*format/8"

Example 3. Simple types.

if <field type="ATOM" name="property" /> 
then <sizeof>property</sizeof> is 4.

if <field type="CARD8" name="mode" enum="PropMode" />
then <sizeof>PropMode</sizeof> is 1.

There is an alternative approach. We could extend already existed and
specified <localfield> in the following way:

<localfield type="identifier" name="identifier">expression</localfield>

Then we could write

<localfield type="CARD32" name="vendor_size">
  <fieldref>vendor_len</fieldref>
</localfield>
<list type="char" name="vendor">
  <fieldref>vendor_size</fieldref>
</list>
<localfield type="CARD32" name="data_size">
  <op op="/">
    <op op="*">
      <fieldref>data_len</fieldref>
      <fieldref>format</fieldref>
    </op>
    <value>8</value>
  </op>
</localfield>
<list type="void" name="data">
  <fieldref>data_size</fieldref>
</list>

PADDING
=======

After examining a full set of X Protocol extensions which are
available in XCB I conclude that the following form is suitable to
cover different padding schemas:

<pad align="integer">expression</pad>

If the number of unused bytes is variable, the encode-form, as it
described in the X Protocol Specification, typically is:

      p		unused, p=pad(E),

where E is some expression, and pad(E) is the number of bytes needed
to round E up to a multiple of integer i from the align
attribute. Typically, the value of align attribute is 4. The content
of the tag is an expression giving the size in bytes. The expression
usually includes the references to the size(s) of lists or fields from
the structure.

Example 1. Pad for a list of simple types and structures.

<list type="STR" name="names">
  <fieldref>names_len</fieldref>
</list>
<pad align="4"><sizeof>names</sizeof></pad>

Example 2. Structure KB_LISTING from XKB specification has 2-byte (!)
alignment.

2    CARD16     flags
2    n          length
n    STRING8    string
p               unused, p=pad(n) to a 2-byte boundary 

<struct name="Listing">
  <field name="flags" type="CARD16" />
  <field name="length" type="CARD16" />
  <list name="string" type="STRING8">
    <fieldref>length</fieldref>
  </list>
  <pad align="2"><sizeof>string</sizeof></pad>
</struct>

Example 3. Structure SYSTEMCOUNTER from XSync has more complex
alignment scheme: pad is a function on sizes of two adjacent fields.

4    COUNTER    counter
8    INT64      resolution
2    n          length of name in bytes
n    STRING8    name
p               pad, p=pad(n+2)

<struct name="SYSTEMCOUNTER">
  <field type="COUNTER" name="counter" />
  <field type="INT64" name="resolution" />
  <field type="CARD16" name="name_len" />
  <list type="char" name="name">
    <fieldref>name_len</fieldref>
  </list>
  <pad align="4">
    <op op="+">
       <sizeof>name</sizeof>
       <value>2</value> <!-- or <sizeof>name_len</sizeof> -->
    </op>
  </pad>
</struct>

Example 4. Even more complex alignment scheme. "ListComponents"
request from XKB has the pad

p        unused, p=pad(6+m+k+t+c+s+g)

<request name="ListComponents" opcode="22">
  <field name="deviceSpec" type="DeviceSpec" />
  <field name="maxNames" type="CARD16" />
  <field name="keymapsSpecLen" type="CARD8" />
  <list name="keymapsSpec" type="STRING8">
    <fieldref>keymapsSpecLen</fieldref>
  </list>
  <field name="keycodesSpecLen" type="CARD8" />
    <list name="keycodesSpec" type="STRING8">
    <fieldref>keycodesSpecLen</fieldref>
  </list>
  <field name="typesSpecLen" type="CARD8" />
  <list name="typesSpec" type="STRING8">
    <fieldref>typesSpecLen</fieldref>
  </list>
  <field name="compatMapSpecLen" type="CARD8" />
  <list name="compatMapSpec" type="STRING8">
    <fieldref>compatMapSpecLen</fieldref>
  </list>
  <field name="symbolsSpecLen" type="CARD8" />
  <list name="symbolsSpec" type="STRING8">
    <fieldref>symbolsSpecLen</fieldref>
  </list>
  <field name="geometrySpecLen" type="CARD8" />
  <list name="geometrySpec" type="STRING8">
    <fieldref>geometrySpecLen</fieldref>
  </list>
  <pad align="4">
    <op op="+"><sizeof>keymapsSpec</sizeof>
    <op op="+"><sizeof>keycodesSpec</sizeof>
    <op op="+"><sizeof>typesSpec</sizeof>
    <op op="+"><sizeof>compatMapSpec</sizeof>
    <op op="+"><sizeof>symbolsSpec</sizeof>
    <op op="+"><sizeof>geometrySpec</sizeof>
    <value>6</value>
    </op></op></op></op></op></op>
  </pad>
  <reply>
    ...
  </reply>
</request>

Example 5. <fieldref> may be also used in expression to calculate size
for padding. In the following example the size of alignment is
calculated from the three adjacent lists which have the same size. The
lists follow one after another without any padding between
them. randr.xml:

<request name="SetCrtcGamma" opcode="24">
  <field type="CRTC" name="crtc" />
  <field type="CARD16" name="size" />
  <pad bytes="2"/>
  <list type="CARD16" name="red">
    <fieldref>size</fieldref>
  </list>
  <list type="CARD16" name="green">
    <fieldref>size</fieldref>
  </list>
  <list type="CARD16" name="blue">
    <fieldref>size</fieldref>
  </list>
  <pad align="4">
    <op op="*">
      <fieldref>size</fieldref>
      <value>6</value>
    </op>
  </pad>
</request>

I've written a patch. Changes:

* Add the alignment pads to the structures, requests, and replies
  where the padding is specified. I've made this change for xproto.xml
  and every extension. List of structures and requests where the
  changes were made is below

* Change xtypes.py in order for it not to process <pad> with "align"
  attribute and not to break a present code generator's behavior. This
  is temporary stub.

* Update documentation xml-xcb.txt for <sizeof> and <pad> tags.

Please, review.

A list of changed structures and requests groupped by extension
===============================================================

- [X] xproto.xml

      * Structs

	HOST
	SetupRequest
	SetupFailed
	Setup

      * Requests

	InternAtom
	GetAtomName
	ChangeProperty
	GetProperty
	OpenFont
	QueryTextExtents
	ListFonts
	ListFontsWithInfo
	SetFontPath
	GetFontPath
	SetDashes
	PutImage
	PolyText8
	PolyText16
	ImageText8
	ImageText16
	AllocNamedColor
	StoreNamedColor
	LookupColor
	QueryExtension
	ListExtensions
	ChangeHosts
	SetPointerMapping
	GetPointerMapping

- [X] dri2.xml

      * Requests

	Connect

- [X] randr.xml

      * Requests

	GetScreenInfo
	GetScreenResources
	GetOutputInfo
	ChangeOutputProperty
	GetOutputProperty
	CreateMode
	GetCrtcGamma
	SetCrtcGamma
	SetCrtcTransform
	GetCrtcTransform

- [X] render.xml

      * Requests

	AddGlyphs
	CompositeGlyphs8
	CompositeGlyphs16
	CompositeGlyphs32
	QueryFilters
	SetPictureFilter

- [X] sync.xml

      * Structs

	SYSTEMCOUNTER

- [X] xf86dri.xml

      * Requests

	OpenConnection
	GetClientDriverName

- [X] xf86vidmode.xml

      * Requests

	GetMonitor

- [X] xfixes.xml

      * Requests

	SetCursorName
	GetCursorName
	GetCursorImageAndName
	ChangeCursorByName

- [X] xinput.xml

      * Requests

	OpenDevice
	GetDeviceButtonMapping
	SetDeviceButtonMapping

- [X] xselinux.xml

      * Structs

	ListItem

      * Requests

	SetDeviceCreateContext
	GetDeviceCreateContext
	SetDeviceContext
	GetDeviceContext
	SetWindowCreateContext
	GetWindowCreateContext
	GetWindowContext
	SetPropertyCreateContext
	GetPropertyCreateContext
	SetPropertyUseContext
	GetPropertyUseContext
	GetPropertyContext
	GetPropertyDataContext
	SetSelectionCreateContext
	GetSelectionCreateContext
	SetSelectionUseContext
	GetSelectionUseContext
	GetSelectionContext
	GetSelectionDataContext
	GetClientContext

- [X] xv.xml

      * Structs

	AdaptorInfo
	EncodingInfo

      * Requests

	QueryAdaptor
	QueryPortAttributes
	PutImage

- [X] xkb.xml

      * Structs

	CountedString16

      * Requests

	SelectEvents
	GetMap
	SetMap
	SetNamedIndicator
	GetNames
	SetNames
	ListComponents
	GetKbdByName
	GetDeviceInfo
	SetDebuggingFlags

- [X] xprint.xml

      * Structs

	PRINTER

      * Requests

	PrintGetPrinterList
	CreateContext
	PrintPutDocumentData
	PrintGetDocumentData
	PrintGetOneAttributes
	PrintSetAttributes

- [X] glx.xml

      * Requests

	RenderLarge
	VendorPrivate
	VendorPrivateWithData
	QueryServerString
	ClientInfo
	GetBooleanv
	GetPixelMapusv
	GetString

Checked. No changes required:

- [X] bigreq.xml
- [X] composite.xml
- [X] xc_misc.xml
- [X] damage.xml
- [X] dpms.xml
- [X] xtest.xml
- [X] xvmc.xml
- [X] xinerama.xml
- [X] res.xml
- [X] screensaver.xml
- [X] shape.xml
- [X] shm.xml
- [X] xevie.xml
- [X] ge.xml
- [X] record.xml

-------------- next part --------------
A non-text attachment was scrubbed...
Name: xcb_alignment_padding.patch
Type: text/x-diff
Size: 42478 bytes
Desc: Patch for alignment padding
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20101108/70dbbbf5/attachment-0001.patch>