[PATCH] update protocol specification to match wire protocol

[Pekka Paalanen]

On Fri, 5 Sep 2014 19:18:44 -0500
Paul Sbarra <sbarra.paul at gmail.com> wrote:

> On Fri, Sep 5, 2014 at 7:51 AM, Pekka Paalanen <ppaalanen at gmail.com> wrote:
> 
> 
> > I took a look at both of them, you are making an incompatible change to
> > wayland.xml, and breaking the generator.
> >
> > Essentially you are breaking the unwritten specification on how the XML
> > files are processed into wire format and language bindings.
> > Wayland-scanner is not the only generator, and wayland.xml is not the
> > only XML file in existence.
> >
> > If you look carefully, you see that there is absolutely no
> > documentation on how to generate the wire protocol or C function
> > signatures from the XML. It is all undocumented.
> 
> 
> Thanks for the continued dialog.  I was also surprised that the reqest /
> event opcodes were not specified in the specification but was mentioned in
> the bug report for improved documentation.
> 
> The one major critique that you pointed out in your previous message is
> that this patch is completely non-generic and written under the (apparently
> false) assumption that the scanner is only used to provide the code-gen for
> the wayland.xml provided in the wayland repo.  The intention was to
> possibly elicit help to replace the string comparisons with something more
> generic.
> 
> If indeed the scanner application is used by external projects or to parse
> external specifications (as you'd mentioned custom extensions) then indeed
> this changeset is not generic enough for that case.  I think that's
> probably the main factor to why the unique rule is needed, because I don't
> think it's possible to come to a generic solution without also changing the
> api.

Yes, if you look at Weston, there are at least half a dozen
protocol XML files more. Quite likely every compositor project will
have some of its own extensions.

The generic rule currently used for XML is:

- If a new_id argument is with the interface attribute, generate
  only one parameter, because everyone knows the interface at
  runtime already. (Everyone has the same XML file.)

- If a new_id argument is without the interface attribute, generate
  the three parameters, so that the sender can encode the object
  interface and version at runtime.

Even if we could change the ABI, I'm not sure what would be more
generic.

> At least now there's some dialog in the mailing list for others to consider
> until the docs get updated.  Again I thank you for taking the time (and
> patience) to help me get up to speed.

No worries, and sorry if I came out very blunt.


Thanks,
pq