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

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

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

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@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/xen-devel