Re: [PATCH v3 for-4.14] pvcalls: Document correctly and explicitely the padding for all arches

[Ian Jackson <ian.jackson@xxxxxxxxxx>]

Julien Grall writes ("Re: [PATCH v3 for-4.14] pvcalls: Document correctly and 
explicitely the padding for all arches"):
> (+ Committers)
...
> As Jan and you disagree on the approach, I would like to get more input.
> 
> To summarize the discussion, the document for PV calls and the public 
> headers don't match when describing the padding. There is a disagreement 
> on which of the two are the authority and therefore which one to fix.
> 
> Does anyone else have a preference on the approach?

Hi.

>[Jan:]
>> I am leaning towards the header as authoritative because this has
>> always been the case in the past and nothing in xen.git says
>> otherwise. However I am not a user of pvcalls, so I don't really have
>> any big incentive to go either way.

I think the practice of using headers as protocol specs is not a
particularly good one.  Certainly my expectations anywhere outside the
Xen Project is that if there's a doc, that is at the very least on par
with any header file.  Of course there are possible compatibility
implications:

> Yeah, we are risking breaking one set of users either way :-/
> In reality, we are using pvcalls on arm64 in a new project (but it is
> still very green). I am not aware of anybody using pvcalls on x86
> (especially x86_32).
> 
> I would prefer to honor the pvcalls.pandoc specification because that is
> what it was meant to be, and also leads to a better protocol
> specification.

pvcalls in Linux is Tech Preview / Experimental AFAICT ?  I think that
means we can de jure change things like this.

And it seems that we don't think there are any actual users who would
experience compatibility problems.

So I don't think the compatibility concerns are a reason not to change
the header rather than the document.

So I think my conclusion is the same as Julien's: we should change the
header to match the doc.

> >> For the future, I would highly suggest writing down the support
> >> decision in xen.git. This would avoid such debate on what is the
> >> authority...
> > 
> > Yes that's the way to go

Maybe it would be worth putting a note somewhere in the headers saying
the headers are provided for convenience but that the ABIs and
protocols are as specified in the docs (at least where docs exist).

Ian.