Re: [v2 1/6] KVM: arm64: Document PV-lock interface

[Usama Arif]

On 07/11/2022 17:56, Punit Agrawal wrote:
> Hi Usama,
>
> Usama Arif <usama.arif@xxxxxxxxxxxxx> writes:
>
> > Introduce a paravirtualization interface for KVM/arm64 to obtain whether
> > the VCPU is currently running or not.
> >
> > The PV lock structure of the guest is allocated by user space.
> >
> > A hypercall interface is provided for the guest to interrogate the
> > location of the shared memory structures.
> >
> > Signed-off-by: Zengruan Ye <yezengruan@xxxxxxxxxx>
> > Signed-off-by: Usama Arif <usama.arif@xxxxxxxxxxxxx>
> > ---
> >   Documentation/virt/kvm/arm/index.rst    |  1 +
> >   Documentation/virt/kvm/arm/pvlock.rst   | 52 +++++++++++++++++++++++++
> >   Documentation/virt/kvm/devices/vcpu.rst | 25 ++++++++++++
> >   3 files changed, 78 insertions(+)
> >   create mode 100644 Documentation/virt/kvm/arm/pvlock.rst
> >
> > diff --git a/Documentation/virt/kvm/arm/index.rst b/Documentation/virt/kvm/arm/index.rst
> > index e84848432158..b8499dc00a6a 100644
> > --- a/Documentation/virt/kvm/arm/index.rst
> > +++ b/Documentation/virt/kvm/arm/index.rst
> > @@ -10,4 +10,5 @@ ARM
> >      hyp-abi
> >      hypercalls
> >      pvtime
> > +   pvlock
> >      ptp_kvm
> > diff --git a/Documentation/virt/kvm/arm/pvlock.rst b/Documentation/virt/kvm/arm/pvlock.rst
> > new file mode 100644
> > index 000000000000..d3c391b16d36
> > --- /dev/null
> > +++ b/Documentation/virt/kvm/arm/pvlock.rst
> > @@ -0,0 +1,52 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +Paravirtualized lock support for arm64
> > +======================================
> > +
> > +KVM/arm64 provides a hypervisor service call for paravirtualized guests to
> > +determine whether a VCPU is currently running or not.
> > +
> > +A new SMCCC compatible hypercall is defined:
> > +
> > +* ARM_SMCCC_VENDOR_HYP_KVM_PV_LOCK_FUNC_ID:   0xC6000002
> > +
> > +ARM_SMCCC_VENDOR_HYP_KVM_PV_LOCK_FUNC_ID
> > +
> > +    ============= ========    ==========================================
> > +    Function ID:  (uint32)    0xC6000002
> > +    Return value: (int64)     IPA of the pv lock data structure for this
> > +                              VCPU. On failure:
> > +                              NOT_SUPPORTED (-1)
> > +    ============= ========    ==========================================
> > +
> > +The IPA returned by PV_LOCK_PREEMPTED should be mapped by the guest as normal
> > +memory with inner and outer write back caching attributes, in the inner
> > +shareable domain.
> > +
> > +PV_LOCK_PREEMPTED returns the structure for the calling VCPU.
> > +
> > +PV lock state
> > +-------------
> > +
> > +The structure pointed to by the PV_LOCK_PREEMPTED hypercall is as follows:
> > +
> > ++-----------+-------------+-------------+---------------------------------+
> > +| Field     | Byte Length | Byte Offset | Description                     |
> > ++===========+=============+=============+=================================+
> > +| preempted |      8      |      0      | Indicate if the VCPU that owns  |
> > +|           |             |             | this struct is running or not.  |
> > +|           |             |             | Non-zero values mean the VCPU   |
> > +|           |             |             | has been preempted. Zero means  |
> > +|           |             |             | the VCPU is not preempted.      |
> > ++-----------+-------------+-------------+---------------------------------+
> > +
> > +The preempted field will be updated to 1 by the hypervisor prior to scheduling
> > +a VCPU. When the VCPU is scheduled out, the preempted field will be updated
> > +to 0 by the hypervisor.
>
> The text above doesn't match the description in the table. Please update
> the texts to align them with the code.
Will make it clearer in the next revision. Thanks.

> [...]