From: Christoffer Dall <cdall@linaro.org> To: "Paolo Bonzini" <pbonzini@redhat.com>, "Radim Krčmář" <rkrcmar@redhat.com> Cc: Marc Zyngier <marc.zyngier@arm.com>, Christoffer Dall <cdall@linaro.org>, kvmarm@lists.cs.columbia.edu, kvm@vger.kernel.org, linux-arm-kernel@lists.infradead.org Subject: [PULL 69/79] arm/arm64: Add hyp-stub API documentation Date: Sun, 23 Apr 2017 19:09:19 +0200 [thread overview] Message-ID: <20170423170929.27334-70-cdall@linaro.org> (raw) In-Reply-To: <20170423170929.27334-1-cdall@linaro.org> From: Marc Zyngier <marc.zyngier@arm.com> In order to help people understanding the hyp-stub API that exists between the host kernel and the hypervisor mode (whether a hypervisor has been installed or not), let's document said API. As with any form of documentation, I expect it to become obsolete and completely misleading within 20 minutes after having being merged. Acked-by: Russell King <rmk+kernel@armlinux.org.uk> Acked-by: Catalin Marinas <catalin.marinas@arm.com> Signed-off-by: Marc Zyngier <marc.zyngier@arm.com> Signed-off-by: Christoffer Dall <cdall@linaro.org> --- Documentation/virtual/kvm/arm/hyp-abi.txt | 53 +++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 Documentation/virtual/kvm/arm/hyp-abi.txt diff --git a/Documentation/virtual/kvm/arm/hyp-abi.txt b/Documentation/virtual/kvm/arm/hyp-abi.txt new file mode 100644 index 0000000..a20a0be --- /dev/null +++ b/Documentation/virtual/kvm/arm/hyp-abi.txt @@ -0,0 +1,53 @@ +* Internal ABI between the kernel and HYP + +This file documents the interaction between the Linux kernel and the +hypervisor layer when running Linux as a hypervisor (for example +KVM). It doesn't cover the interaction of the kernel with the +hypervisor when running as a guest (under Xen, KVM or any other +hypervisor), or any hypervisor-specific interaction when the kernel is +used as a host. + +On arm and arm64 (without VHE), the kernel doesn't run in hypervisor +mode, but still needs to interact with it, allowing a built-in +hypervisor to be either installed or torn down. + +In order to achieve this, the kernel must be booted at HYP (arm) or +EL2 (arm64), allowing it to install a set of stubs before dropping to +SVC/EL1. These stubs are accessible by using a 'hvc #0' instruction, +and only act on individual CPUs. + +Unless specified otherwise, any built-in hypervisor must implement +these functions (see arch/arm{,64}/include/asm/virt.h): + +* r0/x0 = HVC_SET_VECTORS + r1/x1 = vectors + + Set HVBAR/VBAR_EL2 to 'vectors' to enable a hypervisor. 'vectors' + must be a physical address, and respect the alignment requirements + of the architecture. Only implemented by the initial stubs, not by + Linux hypervisors. + +* r0/x0 = HVC_RESET_VECTORS + + Turn HYP/EL2 MMU off, and reset HVBAR/VBAR_EL2 to the initials + stubs' exception vector value. This effectively disables an existing + hypervisor. + +* r0/x0 = HVC_SOFT_RESTART + r1/x1 = restart address + x2 = x0's value when entering the next payload (arm64) + x3 = x1's value when entering the next payload (arm64) + x4 = x2's value when entering the next payload (arm64) + + Mask all exceptions, disable the MMU, move the arguments into place + (arm64 only), and jump to the restart address while at HYP/EL2. This + hypercall is not expected to return to its caller. + +Any other value of r0/x0 triggers a hypervisor-specific handling, +which is not documented here. + +The return value of a stub hypercall is held by r0/x0, and is 0 on +success, and HVC_STUB_ERR on error. A stub hypercall is allowed to +clobber any of the caller-saved registers (x0-x18 on arm64, r0-r3 and +ip on arm). It is thus recommended to use a function call to perform +the hypercall. -- 2.9.0
WARNING: multiple messages have this Message-ID (diff)
From: cdall@linaro.org (Christoffer Dall) To: linux-arm-kernel@lists.infradead.org Subject: [PULL 69/79] arm/arm64: Add hyp-stub API documentation Date: Sun, 23 Apr 2017 19:09:19 +0200 [thread overview] Message-ID: <20170423170929.27334-70-cdall@linaro.org> (raw) In-Reply-To: <20170423170929.27334-1-cdall@linaro.org> From: Marc Zyngier <marc.zyngier@arm.com> In order to help people understanding the hyp-stub API that exists between the host kernel and the hypervisor mode (whether a hypervisor has been installed or not), let's document said API. As with any form of documentation, I expect it to become obsolete and completely misleading within 20 minutes after having being merged. Acked-by: Russell King <rmk+kernel@armlinux.org.uk> Acked-by: Catalin Marinas <catalin.marinas@arm.com> Signed-off-by: Marc Zyngier <marc.zyngier@arm.com> Signed-off-by: Christoffer Dall <cdall@linaro.org> --- Documentation/virtual/kvm/arm/hyp-abi.txt | 53 +++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 Documentation/virtual/kvm/arm/hyp-abi.txt diff --git a/Documentation/virtual/kvm/arm/hyp-abi.txt b/Documentation/virtual/kvm/arm/hyp-abi.txt new file mode 100644 index 0000000..a20a0be --- /dev/null +++ b/Documentation/virtual/kvm/arm/hyp-abi.txt @@ -0,0 +1,53 @@ +* Internal ABI between the kernel and HYP + +This file documents the interaction between the Linux kernel and the +hypervisor layer when running Linux as a hypervisor (for example +KVM). It doesn't cover the interaction of the kernel with the +hypervisor when running as a guest (under Xen, KVM or any other +hypervisor), or any hypervisor-specific interaction when the kernel is +used as a host. + +On arm and arm64 (without VHE), the kernel doesn't run in hypervisor +mode, but still needs to interact with it, allowing a built-in +hypervisor to be either installed or torn down. + +In order to achieve this, the kernel must be booted at HYP (arm) or +EL2 (arm64), allowing it to install a set of stubs before dropping to +SVC/EL1. These stubs are accessible by using a 'hvc #0' instruction, +and only act on individual CPUs. + +Unless specified otherwise, any built-in hypervisor must implement +these functions (see arch/arm{,64}/include/asm/virt.h): + +* r0/x0 = HVC_SET_VECTORS + r1/x1 = vectors + + Set HVBAR/VBAR_EL2 to 'vectors' to enable a hypervisor. 'vectors' + must be a physical address, and respect the alignment requirements + of the architecture. Only implemented by the initial stubs, not by + Linux hypervisors. + +* r0/x0 = HVC_RESET_VECTORS + + Turn HYP/EL2 MMU off, and reset HVBAR/VBAR_EL2 to the initials + stubs' exception vector value. This effectively disables an existing + hypervisor. + +* r0/x0 = HVC_SOFT_RESTART + r1/x1 = restart address + x2 = x0's value when entering the next payload (arm64) + x3 = x1's value when entering the next payload (arm64) + x4 = x2's value when entering the next payload (arm64) + + Mask all exceptions, disable the MMU, move the arguments into place + (arm64 only), and jump to the restart address while at HYP/EL2. This + hypercall is not expected to return to its caller. + +Any other value of r0/x0 triggers a hypervisor-specific handling, +which is not documented here. + +The return value of a stub hypercall is held by r0/x0, and is 0 on +success, and HVC_STUB_ERR on error. A stub hypercall is allowed to +clobber any of the caller-saved registers (x0-x18 on arm64, r0-r3 and +ip on arm). It is thus recommended to use a function call to perform +the hypercall. -- 2.9.0
next prev parent reply other threads:[~2017-04-23 17:09 UTC|newest] Thread overview: 163+ messages / expand[flat|nested] mbox.gz Atom feed top 2017-04-23 17:08 [PULL 00/79] KVM/ARM Changes for v4.12 Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 01/79] arm64: sysreg: sort by encoding Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 02/79] arm64: sysreg: add debug system registers Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 03/79] arm64: sysreg: add performance monitor registers Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 04/79] arm64: sysreg: subsume GICv3 sysreg definitions Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 05/79] arm64: sysreg: add physical timer registers Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 06/79] arm64: sysreg: add register encodings used by KVM Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 07/79] arm64: sysreg: add Set/Way sys encodings Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 08/79] KVM: arm64: add SYS_DESC() Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 09/79] KVM: arm64: Use common debug sysreg definitions Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 10/79] KVM: arm64: Use common performance monitor " Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 11/79] KVM: arm64: Use common GICv3 " Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 12/79] KVM: arm64: Use common physical timer " Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 13/79] KVM: arm64: use common invariant " Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 14/79] KVM: arm64: Use common " Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 15/79] KVM: arm64: Use common Set/Way sys definitions Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 16/79] kvm: arm/arm64: Rework gpa callback handlers Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 17/79] KVM: arm/arm64: vgic: Defer touching GICH_VMCR to vcpu_load/put Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 18/79] KVM: arm/arm64: vgic: Avoid flushing vgic state when there's no pending IRQ Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 19/79] KVM: arm/arm64: vgic: Get rid of live_lrs Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 20/79] KVM: arm/arm64: vgic: Only set underflow when actually out of LRs Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 21/79] KVM: arm/arm64: vgic: Get rid of unnecessary process_maintenance operation Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 22/79] KVM: arm/arm64: vgic: Get rid of unnecessary save_maint_int_state Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 23/79] KVM: arm/arm64: vgic: Get rid of MISR and EISR fields Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 24/79] KVM: arm/arm64: vgic: Implement early VGIC init functionality Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 25/79] KVM: arm/arm64: vgic: Don't check vgic_initialized in sync/flush Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 26/79] KVM: arm/arm64: vgic: Improve sync_hwstate performance Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 27/79] arm64: KVM: PMU: Refactor pmu_*_el0_disabled Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 28/79] arm64: KVM: PMU: Inject UNDEF exception on illegal register access Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 29/79] arm64: KVM: PMU: Inject UNDEF on non-privileged accesses Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 30/79] arm64: KVM: Make unexpected reads from WO registers inject an undef Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 31/79] arm64: KVM: PMU: Inject UNDEF on read access to PMSWINC_EL0 Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 32/79] arm64: KVM: Treat sysreg accessors returning false as successful Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 33/79] arm64: KVM: Do not corrupt registers on failed 64bit CP read Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 34/79] arm: KVM: Make unexpected register accesses inject an undef Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 35/79] arm: KVM: Treat CP15 accessors returning false as successful Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 36/79] arm64: hyp-stub: Stop pointlessly clobbering lr Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 37/79] arm64: KVM: Move lr save/restore to do_el2_call Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 38/79] arm64: hyp-stub: Don't save lr in the EL1 code Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 39/79] arm64: hyp-stub: Define a return value for failed stub calls Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 40/79] arm64: hyp-stub: Update documentation in asm/virt.h Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 41/79] arm64: hyp-stub: Implement HVC_RESET_VECTORS stub hypercall Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 42/79] arm64: KVM: Implement HVC_RESET_VECTORS stub hypercall in the init code Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 43/79] arm64: KVM: Implement HVC_GET_VECTORS " Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 44/79] arm64: KVM: Allow the main HYP code to use the init hyp stub implementation Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 45/79] arm64: KVM: Convert __cpu_reset_hyp_mode to using __hyp_reset_vectors Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 46/79] arm64: KVM: Implement HVC_SOFT_RESTART in the init code Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 47/79] ARM: hyp-stub: improve ABI Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 48/79] ARM: soft-reboot into same mode that we entered the kernel Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:08 ` [PULL 49/79] ARM: KVM: Convert KVM to use HVC_GET_VECTORS Christoffer Dall 2017-04-23 17:08 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 50/79] ARM: Update cpu_v7_reset documentation Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 51/79] ARM: hyp-stub: Use r1 for the soft-restart address Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 52/79] ARM: Expose the VA/IDMAP offset Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 53/79] ARM: hyp-stub: Define a return value for failed stub calls Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 54/79] ARM: hyp-stub: Implement HVC_RESET_VECTORS stub hypercall Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 55/79] ARM: KVM: Implement HVC_RESET_VECTORS stub hypercall in the init code Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 56/79] ARM: KVM: Implement HVC_GET_VECTORS " Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 57/79] ARM: KVM: Allow the main HYP code to use the init hyp stub implementation Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 58/79] ARM: KVM: Convert __cpu_reset_hyp_mode to using __hyp_reset_vectors Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 59/79] ARM: KVM: Implement HVC_SOFT_RESTART in the init code Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 60/79] ARM: KVM: Gracefully handle hyp-stubs being restored from under our feet Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 61/79] arm/arm64: KVM: Use __hyp_reset_vectors() directly Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 62/79] arm/arm64: KVM: Remove kvm_get_idmap_start Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 63/79] arm/arm64: KVM: Use HVC_RESET_VECTORS to reinit HYP mode Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 64/79] ARM: decompressor: Remove __hyp_get_vectors usage Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 65/79] ARM: hyp-stub/KVM: Kill __hyp_get_vectors Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 66/79] arm64: " Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 67/79] arm64: hyp-stub: Zero x0 on successful stub handling Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 68/79] ARM: hyp-stub: Zero r0 " Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall [this message] 2017-04-23 17:09 ` [PULL 69/79] arm/arm64: Add hyp-stub API documentation Christoffer Dall 2017-04-23 17:09 ` [PULL 70/79] KVM: arm/arm64: Cleanup the arch timer code's irqchip checking Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 71/79] KVM: arm/arm64: Add ARM user space interrupt signaling ABI Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 72/79] KVM: arm/arm64: Support arch timers with a userspace gic Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 73/79] KVM: arm/arm64: Report PMU overflow interrupts to userspace irqchip Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 74/79] KVM: arm/arm64: Advertise support for KVM_CAP_ARM_USER_IRQ Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 75/79] KVM: arm/arm64: fix races in kvm_psci_vcpu_on Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 76/79] KVM: arm/arm64: vgic-v3: De-optimize VMCR save/restore when emulating a GICv2 Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 77/79] KVM: arm/arm64: vgic-v3: Fix off-by-one LR access Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 78/79] ARM: hyp-stub: Fix Thumb-2 compilation Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-23 17:09 ` [PULL 79/79] ARM: KVM: Fix idmap stub entry when running Thumb-2 code Christoffer Dall 2017-04-23 17:09 ` Christoffer Dall 2017-04-27 15:34 ` [PULL 00/79] KVM/ARM Changes for v4.12 Paolo Bonzini 2017-04-27 15:34 ` Paolo Bonzini
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20170423170929.27334-70-cdall@linaro.org \ --to=cdall@linaro.org \ --cc=kvm@vger.kernel.org \ --cc=kvmarm@lists.cs.columbia.edu \ --cc=linux-arm-kernel@lists.infradead.org \ --cc=marc.zyngier@arm.com \ --cc=pbonzini@redhat.com \ --cc=rkrcmar@redhat.com \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.