Re: [PATCH v3] Loongarch: KVM: Add KVM hypercalls documentation for LoongArch

[maobibo]

On 2024/8/28 下午12:59, Dandan Zhang wrote:
> From: Bibo Mao <maobibo@xxxxxxxxxxx>
>
> Add documentation topic for using pv_virt when running as a guest
> on KVM hypervisor.
>
> Signed-off-by: Bibo Mao <maobibo@xxxxxxxxxxx>
> Signed-off-by: Xianglai Li <lixianglai@xxxxxxxxxxx>
> Co-developed-by: Mingcong Bai <jeffbai@xxxxxxx>
> Signed-off-by: Mingcong Bai <jeffbai@xxxxxxx>
> Link: https://lore.kernel.org/all/5c338084b1bcccc1d57dce9ddb1e7081@xxxxxxx/
> Signed-off-by: Dandan Zhang <zhangdandan@xxxxxxxxxxxxx>
> ---
>   Documentation/virt/kvm/index.rst              |  1 +
>   .../virt/kvm/loongarch/hypercalls.rst         | 89 +++++++++++++++++++
>   Documentation/virt/kvm/loongarch/index.rst    | 10 +++
>   MAINTAINERS                                   |  1 +
>   4 files changed, 101 insertions(+)
>   create mode 100644 Documentation/virt/kvm/loongarch/hypercalls.rst
>   create mode 100644 Documentation/virt/kvm/loongarch/index.rst
>
> 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..dd96ded5d17d
> --- /dev/null
> +++ b/Documentation/virt/kvm/loongarch/hypercalls.rst
> @@ -0,0 +1,89 @@
> +.. 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. Up to five arguments may be placed in registers a1 - a5.
> +The return value is placed in v0 (an alias of a0).
> +
> +Source code for this interface can be found in arch/loongarch/kvm*.
> +
> +Querying for existence
> +======================
> +
> +To determine if the host is running on KVM, we can utilize the cpucfg()
> +function at index CPUCFG_KVM_BASE (0x40000000).
> +
> +The CPUCFG_KVM_BASE range, spanning from 0x40000000 to 0x400000FF, The
> +CPUCFG_KVM_BASE range between 0x40000000 - 0x400000FF is marked as reserved.
> +Consequently, all current and future processors will not implement any
> +feature within this range.
> +
> +On a KVM-virtualized Linux system, a read operation on cpucfg() at index
> +CPUCFG_KVM_BASE (0x40000000) returns the magic string 'KVM\0'.
> +
> +Once you have determined that your host is running on a paravirtualization-
> +capable KVM, you may now use hypercalls as described below.
> +
> +KVM hypercall ABI
> +=================
> +
> +The KVM hypercall ABI is simple, with one scratch register a0 (v0) and at most
> +five generic registers (a1 - a5) used as input parameters. The FP (Floating-
> +point) and vector registers are not utilized as input registers and must
> +remain unmodified during a hypercall.
> +
> +Hypercall functions can be inlined as it only uses one scratch register.
> +
> +The parameters are as follows:
> +
> +	========	================	================
> +	Register	IN			OUT
> +	========	================	================
> +	a0		function number		Return	code
> +	a1		1st	parameter	-
> +	a2		2nd	parameter	-
> +	a3		3rd	parameter	-
> +	a4		4th	parameter	-
> +	a5		5th	parameter	-
> +	========	================	================
> +
> +The return codes may be one of the following:
> +
> +	====		=========================
> +	Code		Meaning
> +	====		=========================
> +	0		Success
> +	-1		Hypercall not implemented
> +	-2		Bad Hypercall parameter
> +	====		=========================
> +
> +KVM Hypercalls Documentation
> +============================
> +
> +The template for each hypercall is as follows:
> +
> +1. Hypercall name
> +2. Purpose
> +
> +1. KVM_HCALL_FUNC_IPI
> +------------------------
> +
> +:Purpose: Send IPIs to multiple vCPUs.
> +
> +- a0: KVM_HCALL_FUNC_IPI
> +- a1: Lower part of the bitmap for destination physical CPUIDs
> +- a2: Higher part of the bitmap for destination physical CPUIDs
> +- a3: The lowest physical CPUID in the bitmap
> +
> +The hypercall lets a guest send multiple IPIs (Inter-Process Interrupts) with
> +at most 128 destinations per hypercall. The destinations are represented in a
> +bitmap contained in the first two input registers (a1 and a2).
> +
> +Bit 0 of a1 corresponds to the physical CPUID in the third input register (a3)
> +and bit 1 corresponds to the physical CPUID in a3+1, and so on.
> +
> +PV IPI on LoongArch includes both PV IPI multicast sending and PV IPI receiving,
> +and SWI is used for PV IPI inject since there is no VM-exits accessing SWI registers.
> 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
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 878dcd23b331..c267ad7cc2c5 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -12294,6 +12294,7 @@ L:	kvm@xxxxxxxxxxxxxxx
>   L:	loongarch@xxxxxxxxxxxxxxx
>   S:	Maintained
>   T:	git git://git.kernel.org/pub/scm/virt/kvm/kvm.git
> +F:	Documentation/virt/kvm/loongarch/
>   F:	arch/loongarch/include/asm/kvm*
>   F:	arch/loongarch/include/uapi/asm/kvm*
>   F:	arch/loongarch/kvm/
Reviewed-by: Bibo Mao <maobibo@xxxxxxxxxxx>