[v7,7/7] Documentation: KVM: Add hypercall for LoongArch

Commit Message

Bibo Mao March 15, 2024, 8:11 a.m. UTC

Add documentation topic for using pv_virt when running as a guest
on KVM hypervisor.

Signed-off-by: Bibo Mao <[e-mail]>
---
 Documentation/virt/kvm/index.rst              |  1 +
 .../virt/kvm/loongarch/hypercalls.rst         | 82 +++++++++++++++++++
 Documentation/virt/kvm/loongarch/index.rst    | 10 +++
 3 files changed, 93 insertions(+)
 create mode 100644 Documentation/virt/kvm/loongarch/hypercalls.rst
 create mode 100644 Documentation/virt/kvm/loongarch/index.rst

Comments

WANG Xuerui March 23, 2024, 6:40 p.m. UTC | #1

On 3/15/24 16:11, Bibo Mao wrote:
> [snip]
> +KVM hypercall ABI
> +=================
> +
> +Hypercall ABI on KVM is simple, only one scratch register a0 and at most
> +five generic registers used as input parameter. FP register and vector register
> +is not used for input register and should not be modified during hypercall.
> +Hypercall function can be inlined since there is only one scratch register.

Maybe it's better to describe the list of preserved registers with an 
expression such as "all non-GPR registers shall remain unmodified after 
returning from the hypercall", to guard ourselves against future ISA 
state additions.

But I still maintain that it's better to promise less here, and only 
hint on the extensive preservation of context as an implementation 
detail. It is for not losing our ability to save/restore less in the 
future, should we decide to do so.

Bibo Mao April 2, 2024, 1:15 a.m. UTC | #2

On 2024/3/24 上午2:40, WANG Xuerui wrote:
> On 3/15/24 16:11, Bibo Mao wrote:
>> [snip]
>> +KVM hypercall ABI
>> +=================
>> +
>> +Hypercall ABI on KVM is simple, only one scratch register a0 and at most
>> +five generic registers used as input parameter. FP register and 
>> vector register
>> +is not used for input register and should not be modified during 
>> hypercall.
>> +Hypercall function can be inlined since there is only one scratch 
>> register.
> 
> Maybe it's better to describe the list of preserved registers with an 
> expression such as "all non-GPR registers shall remain unmodified after 
> returning from the hypercall", to guard ourselves against future ISA 
> state additions.
Sorry, I do not understand. What is the meaning of "all non-GPR 
registers"?  Can you give an example?

Regards
Bibo Mao
> 
> But I still maintain that it's better to promise less here, and only 
> hint on the extensive preservation of context as an implementation 
> detail. It is for not losing our ability to save/restore less in the 
> future, should we decide to do so.
>

Patch

diff --git a/Documentation/virt/kvm/index.rst b/Documentation/virt/kvm/index.rst
index ad13ec55ddfe..9ca5a45c2140 100644
--- a/Documentation/virt/kvm/index.rst
+++ b/Documentation/virt/kvm/index.rst
@@ -14,6 +14,7 @@  KVM
    s390/index
    ppc-pv
    x86/index
+   loongarch/index
 
    locking
    vcpu-requests
diff --git a/Documentation/virt/kvm/loongarch/hypercalls.rst b/Documentation/virt/kvm/loongarch/hypercalls.rst
new file mode 100644
index 000000000000..0f61a49c31a9
--- /dev/null
+++ b/Documentation/virt/kvm/loongarch/hypercalls.rst
@@ -0,0 +1,82 @@ 
+.. SPDX-License-Identifier: GPL-2.0
+
+===================================
+The LoongArch paravirtual interface
+===================================
+
+KVM hypercalls use the HVCL instruction with code 0x100, and the hypercall
+number is put in a0 and up to five arguments may be placed in a1-a5, the
+return value is placed in a0.
+
+The code for that interface can be found in arch/loongarch/kvm/*
+
+Querying for existence
+======================
+
+To find out if we're running on KVM or not, cpucfg can be used with index
+CPUCFG_KVM_BASE (0x40000000), cpucfg range between 0x40000000 - 0x400000FF
+is marked as a specially reserved range. All existing and future processors
+will not implement any features in this range.
+
+When Linux is running on KVM, cpucfg with index CPUCFG_KVM_BASE (0x40000000)
+returns magic string "KVM\0"
+
+Once you determined you're running under a PV capable KVM, you can now use
+hypercalls described as follows.
+
+KVM hypercall ABI
+=================
+
+Hypercall ABI on KVM is simple, only one scratch register a0 and at most
+five generic registers used as input parameter. FP register and vector register
+is not used for input register and should not be modified during hypercall.
+Hypercall function can be inlined since there is only one scratch register.
+
+The parameters are as follows:
+
+        ========	=========================	=====================
+	Register	IN			        OUT
+        ========	=========================	=====================
+	a0		function number(Required)       Return code(Required)
+	a1		1st parameter(Optional)		Keep Unmodified
+	a2		2nd parameter(Optional)		Keep Unmodified
+	a3		3rd parameter(Optional)		Keep Unmodified
+	a4		4th parameter(Optional)		Keep Unmodified
+	a5		5th parameter(Optional)		Keep Unmodified
+        ========	=========================	=====================
+
+Return codes can be as follows:
+
+	====		=========================
+	Code		Meaning
+	====		=========================
+	0		Success
+	-1		Hypercall not implemented
+	-2		Hypercall parameter error
+	====		=========================
+
+KVM Hypercalls Documentation
+============================
+
+The template for each hypercall is:
+1. Hypercall name
+2. Purpose
+
+1. KVM_HCALL_FUNC_PV_IPI
+------------------------
+
+:Purpose: Send IPIs to multiple vCPUs.
+
+- a0: KVM_HCALL_FUNC_PV_IPI
+- a1: lower part of the bitmap of destination physical cpu core id
+- a2: higher part of the bitmap of destination physical cpu core id
+- a3: the lowest physical cpu core id in bitmap
+
+The hypercall lets a guest send multicast IPIs, with at most 128
+destinations per hypercall.  The destinations are represented by a bitmap
+contained in the first two arguments (a1 and a2). Bit 0 of a1 corresponds
+to the physical cpu core id in the third argument (a3), bit 1 corresponds
+to the physical cpu core id a3+1, and so on.
+
+Returns success always, it skips current cpu and continues to send ipi to
+next cpu in the bitmap mask if current physical cpu core id is invalid.
diff --git a/Documentation/virt/kvm/loongarch/index.rst b/Documentation/virt/kvm/loongarch/index.rst
new file mode 100644
index 000000000000..83387b4c5345
--- /dev/null
+++ b/Documentation/virt/kvm/loongarch/index.rst
@@ -0,0 +1,10 @@ 
+.. SPDX-License-Identifier: GPL-2.0
+
+=========================
+KVM for LoongArch systems
+=========================
+
+.. toctree::
+   :maxdepth: 2
+
+   hypercalls.rst