[PATCH 10/16] KVM: arm64: Add some documentation for the MMIO guard feature

[Marc Zyngier]

On 2021-07-21 22:17, Andrew Jones wrote:
> On Thu, Jul 15, 2021 at 05:31:53PM +0100, Marc Zyngier wrote:
>> Document the hypercalls user for the MMIO guard infrastructure.
>> 
>> Signed-off-by: Marc Zyngier <maz at kernel.org>
>> ---
>>  Documentation/virt/kvm/arm/index.rst      |  1 +
>>  Documentation/virt/kvm/arm/mmio-guard.rst | 73 
>> +++++++++++++++++++++++
>>  2 files changed, 74 insertions(+)
>>  create mode 100644 Documentation/virt/kvm/arm/mmio-guard.rst
>> 
>> diff --git a/Documentation/virt/kvm/arm/index.rst 
>> b/Documentation/virt/kvm/arm/index.rst
>> index 78a9b670aafe..e77a0ee2e2d4 100644
>> --- a/Documentation/virt/kvm/arm/index.rst
>> +++ b/Documentation/virt/kvm/arm/index.rst
>> @@ -11,3 +11,4 @@ ARM
>>     psci
>>     pvtime
>>     ptp_kvm
>> +   mmio-guard
>> diff --git a/Documentation/virt/kvm/arm/mmio-guard.rst 
>> b/Documentation/virt/kvm/arm/mmio-guard.rst
>> new file mode 100644
>> index 000000000000..a5563a3e12cc
>> --- /dev/null
>> +++ b/Documentation/virt/kvm/arm/mmio-guard.rst
>> @@ -0,0 +1,73 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +==============
>> +KVM MMIO guard
>> +==============
>> +
>> +KVM implements device emulation by handling translation faults to any
>> +IPA range that is not contained a memory slot. Such translation fault
>                                   ^ in                ^ a
> 
>> +is in most cases passed on to userspace (or in rare cases to the host
>> +kernel) with the address, size and possibly data of the access for
>> +emulation.
>> +
>> +Should the guest exit with an address that is not one that 
>> corresponds
>> +to an emulatable device, userspace may take measures that are not the
>> +most graceful as far as the guest is concerned (such as terminating 
>> it
>> +or delivering a fatal exception).
>> +
>> +There is also an element of trust: by forwarding the request to
>> +userspace, the kernel asumes that the guest trusts userspace to do 
>> the
> 
> assumes
> 
>> +right thing.
>> +
>> +The KVM MMIO guard offers a way to mitigate this last point: a guest
>> +can request that only certainly regions of the IPA space are valid as
> 
> certain

Thanks, all corrections applied.

> 
>> +MMIO. Only these regions will be handled as an MMIO, and any other
>> +will result in an exception being delivered to the guest.
>> +
>> +This relies on a set of hypercalls defined in the KVM-specific range,
>> +using the HVC64 calling convention.
>> +
>> +* ARM_SMCCC_KVM_FUNC_MMIO_GUARD_INFO
>> +
>> +    ==============    ========    ================================
>> +    Function ID:      (uint32)    0xC6000002
>> +    Arguments:        none
>> +    Return Values:    (int64)     NOT_SUPPORTED(-1) on error, or
>> +                      (uint64)    Protection Granule (PG) size in
>> +		                  bytes (r0)
>> +    ==============    ========    ================================
>> +
>> +* ARM_SMCCC_KVM_FUNC_MMIO_GUARD_ENROLL
>> +
>> +    ==============    ========    ==============================
>> +    Function ID:      (uint32)    0xC6000003
>> +    Arguments:        none
>> +    Return Values:    (int64)     NOT_SUPPORTED(-1) on error, or
>> +                                  RET_SUCCESS(0) (r0)
>> +    ==============    ========    ==============================
>> +
>> +* ARM_SMCCC_KVM_FUNC_MMIO_GUARD_MAP
>> +
>> +    ==============    ========    
>> ======================================
>> +    Function ID:      (uint32)    0xC6000004
>> +    Arguments:        (uint64)    The base of the PG-sized IPA range
>> +                                  that is allowed to be accessed as
>> +				  MMIO. Must aligned to the PG size (r1)
> 
> align

Hmmm. Ugly mix of tab and spaces. I have no idea what the norm
is here, so I'll just put spaces. I'm sure someone will let me
know if I'm wrong! ;-)

> 
>> +                      (uint64)    Index in the MAIR_EL1 register
>> +		                  providing the memory attribute that
>> +				  is used by the guest (r2)
>> +    Return Values:    (int64)     NOT_SUPPORTED(-1) on error, or
>> +                                  RET_SUCCESS(0) (r0)
>> +    ==============    ========    
>> ======================================
>> +
>> +* ARM_SMCCC_KVM_FUNC_MMIO_GUARD_UNMAP
>> +
>> +    ==============    ========    
>> ======================================
>> +    Function ID:      (uint32)    0xC6000004
> 
> copy+paste error, should be 0xC6000005

Gah, well cpotted.

> 
>> +    Arguments:        (uint64)    The base of the PG-sized IPA range
>> +                                  that is forbidden to be accessed as
> 
> is now forbidden
> 
> or
> 
> was allowed
> 
> or just drop that part of the sentence because its covered by the "and
> have been previously mapped" part. Something like
> 
> PG-sized IPA range aligned to the PG size which has been previously 
> mapped
> (r1)

Picked the latter.

Thanks again,

         M.
-- 
Jazz is not dead. It just smells funny...