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

[Julien Grall <julien@xen.org>]

Hi Ian,

Thank you for your input!

On 24/06/2020 13:04, Ian Jackson wrote:
> 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.

SUPPORT.md suggests this is a Tech Preview, so I agree that we could 
still change the interface.

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

Right, that's what Stefano suggested.

> 
> 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.

Ok, so you are on the same page as Stefano. I will revert to the v1 
change and rework the commit message then.

> 
>>>> 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).

I will write a patch for it.

Cheers,

-- 
Julien Grall