Re: [Xen-devel] [PATCH v2 2/2] docs: Introduce some hypercall page documentation

From: Andrew Cooper <andrew.cooper3@citrix.com>
To: Jan Beulich <JBeulich@suse.com>
Cc: Stefano Stabellini <sstabellini@kernel.org>,
	WeiLiu <wei.liu2@citrix.com>,
	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>,
	George Dunlap <George.Dunlap@eu.citrix.com>,
	Tim Deegan <tim@xen.org>, Julien Grall <julien.grall@arm.com>,
	xen-devel <xen-devel@lists.xenproject.org>,
	Ian Jackson <ian.jackson@citrix.com>
Subject: Re: [Xen-devel] [PATCH v2 2/2] docs: Introduce some hypercall page documentation
Date: Wed, 29 May 2019 04:50:53 -0700	[thread overview]
Message-ID: <c339648b-b6a8-147d-47be-c8ac35351f3d@citrix.com> (raw)
Message-ID: <20190529115053.aEK3-r4g4mIE44g0U2yOXbLmWSLnUR6jiEhaVnJzX9g@z> (raw)
In-Reply-To: <5CEE469802000078002334FE@prv1-mh.provo.novell.com>

On 29/05/2019 09:45, Jan Beulich wrote:
>>>> On 29.05.19 at 06:10, <andrew.cooper3@citrix.com> wrote:
>> This also introduced the top-level Guest Documentation section.
>>
>> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
> Acked-by: Jan Beulich <jbeulich@suse.com>

Thanks.

> with one further remark / question:
>
>> +Hypercall Page
>> +==============
>> +
>> +The hypercall page is a page of guest RAM into which Xen will write suitable
>> +transfer stubs.
>> +
>> +Creating a hypercall page is an isolated operation from Xen's point of view.
>> +It is the guests responsibility to ensure that the hypercall page, once
>> +written by Xen, is mapped with executable permissions so it may be used.
>> +Multiple hypercall pages may be created by the guest, if it wishes.
>> +
>> +The stubs are arranged by hypercall index, and start on 32-byte boundaries.
>> +To invoke a specific hypercall, ``call`` the relevant stub [3]_:
>> +
>> +.. code-block:: none
>> +
>> +  call hypercall_page + index * 32
>> +
>> +There result is an ABI which is invariant of the exact operating mode or
>> +hardware vendor.  This is intended to simplify guest kernel interfaces by
>> +abstracting away the details of how it is currently running.
> Is it worth mentioning here that certain aspects of the hypervisor interface
> (shared data structures) are influenced by the mode the guest is in at the
> time the most recent hypercall page registration (oddly enough alternatively
> the most recent setting of HVM_PARAM_CALLBACK_IRQ) has occurred?

That aspect had crossed my mind, but I decided to leave it for now.

Details on the format of the shared_info page should live primarily in
the shared_info documentation, but I do intend to cross reference
appropriate documentation when both sides are in place.  I'd prefer that
any addition to this document happens when the main shared_info
documentation is done, rather than having an unqualified fraction of the
end result.

Note however that I am taking this opportunity to evaluate the current
behaviour of the areas being documented (hence the cleanup patches), and
I make no guarantees that the details of shared_info latching will be
identical to how they currently are, when the documentation is
eventually complete.

~Andrew

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel