| Message ID | 4769C036576F8816+20240828045950.3484113-1-zhangdandan@uniontech.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v3] Loongarch: KVM: Add KVM hypercalls documentation for LoongArch | expand |
在 2024/8/28 12:59, Dandan Zhang 写道: > 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 If you don't mind, how about translating these into Chinese? If you decide to do so, you don't need to split the patch again, just complete your translation in this patch and add your Co-developed-by tag. Thanks, Yanteng
On 2024/8/29 11:22, YanTeng Si wrote: > > 在 2024/8/28 12:59, Dandan Zhang 写道: >> 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 > If you don't mind, how about translating these into Chinese? If > you decide to do so, you don't need to split the patch again, > just complete your translation in this patch and add your > Co-developed-by tag. I'm afraid that's not feasible. The entire KVM subsystem documentation is currently lacking a Chinese translation, not just for LoongArch. A better approach would be to merge this English document first. In fact, I'm in the process of preparing Chinese translations for the KVM subsystem documentation, and they're on their way. > > Thanks, > Yanteng > Thanks,
在 2024/8/29 11:33, WangYuli 写道: > > On 2024/8/29 11:22, YanTeng Si wrote: >> >> 在 2024/8/28 12:59, Dandan Zhang 写道: >>> 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 >> If you don't mind, how about translating these into Chinese? If >> you decide to do so, you don't need to split the patch again, >> just complete your translation in this patch and add your >> Co-developed-by tag. > > > I'm afraid that's not feasible. > > The entire KVM subsystem documentation is currently lacking a Chinese > translation, not just for LoongArch. You can add other documents to TODOLIST. > > A better approach would be to merge this English document first. It's up to you. > > In fact, I'm in the process of preparing Chinese translations for the > KVM subsystem documentation, and they're on their way. Nice！ To be honest, I've tried to translate kvm's API documentation more than once in the past, but all of them have been halfway because it's too long, and I'm guessing that the review process won't be too smooth either. BTW, I've noticed that v2 is still a work in progress, so please reduce the frequency of sending emails until the v2 and v3 reviews are over. Thanks, Yanteng
On 2024/8/30 13:48, YanTeng Si wrote: > > BTW, I've noticed that v2 is still a work in progress, so please > reduce the frequency of sending emails until the v2 and v3 reviews are > over. > > In fact, the issues identified by zenghui.yu in v2 have been rectified in v3. To ensure ongoing optimization,we kindly request that huacai,bibo,zenghui,and any other relevant parties provide feedback directly on v3. > Thanks, > Yanteng > >
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>
Dandan Zhang <zhangdandan@uniontech.com> writes: > 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 So this generates a nifty build error: > Documentation/virt/kvm/loongarch/hypercalls.rst:46: ERROR: Malformed table. > Text in column margin in table line 5. > > ======== ================ ================ > Register IN OUT > ======== ================ ================ > a0 function number Return code > a1 1st parameter - > a2 2nd parameter - > a3 3rd parameter - > a4 4th parameter - > a5 5th parameter - > ======== ================ ================ The "====" bar for the middle column is too short. *Please* be sure that the documentation actually builds after you make a change. I have fixed this and applied the patch. jon
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/