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

From: Ian Jackson <ian.jackson@citrix.com>
To: Julien Grall <julien@xen.org>
Cc: Juergen Gross <jgross@suse.com>,
	Stefano Stabellini <sstabellini@kernel.org>, Wei Liu <wl@xen.org>,
	Paul Durrant <paul@xen.org>,
	Andrew Cooper <Andrew.Cooper3@citrix.com>,
	Julien Grall <jgrall@amazon.com>,
	George Dunlap <George.Dunlap@citrix.com>,
	"committers@xenproject.org" <committers@xenproject.org>,
	Jan Beulich <jbeulich@suse.com>,
	xen-devel <xen-devel@lists.xenproject.org>,
	Roger Pau Monne <roger.pau@citrix.com>,
	Julien Grall <julien.grall.oss@gmail.com>
Subject: Re: [PATCH v3 for-4.14] pvcalls: Document correctly and explicitely the padding for all arches
Date: Wed, 24 Jun 2020 13:04:25 +0100	[thread overview]
Message-ID: <24307.16713.764272.855818@mariner.uk.xensource.com> (raw)
In-Reply-To: <cefe0cc7-5b1c-4ae2-a160-3857cc131a3d@xen.org>

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.