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

maobibo
2024-09-05T03:58:09Z

On 2024/8/28 下午12:59, Dandan Zhang wrote:
> From: Bibo Mao <maobibo@loongson.cn>
>
> Add documentation topic for using pv_virt when running as a guest
> on KVM hypervisor.
>
> Signed-off-by: Bibo Mao <maobibo@loongson.cn>
> Signed-off-by: Xianglai Li <lixianglai@loongson.cn>
> Co-developed-by: Mingcong Bai <jeffbai@aosc.io>
> Signed-off-by: Mingcong Bai <jeffbai@aosc.io>
> Link: https://lore.kernel.org/all/5c338084b1bcccc1d57dce9ddb1e7081@aosc.io/
> Signed-off-by: Dandan Zhang <zhangdandan@uniontech.com>
> ---
> 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@vger.kernel.org
> L: loongarch@lists.linux.dev
> 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@loongson.cn>