From patchwork Sun Apr 23 17:09:19 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Christoffer Dall X-Patchwork-Id: 9695045 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 229AD60245 for ; Sun, 23 Apr 2017 17:13:33 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 0B6C326530 for ; Sun, 23 Apr 2017 17:13:33 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 00132265B9; Sun, 23 Apr 2017 17:13:32 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.0 required=2.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 83E8626530 for ; Sun, 23 Apr 2017 17:13:32 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1163066AbdDWRNa (ORCPT ); Sun, 23 Apr 2017 13:13:30 -0400 Received: from mail-wr0-f179.google.com ([209.85.128.179]:34073 "EHLO mail-wr0-f179.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1162999AbdDWRKq (ORCPT ); Sun, 23 Apr 2017 13:10:46 -0400 Received: by mail-wr0-f179.google.com with SMTP id z109so79248114wrb.1 for ; Sun, 23 Apr 2017 10:10:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=P7frrxv1EmOfr2DcZFOflYAo4HsU6n88p4VgJqX7K7s=; b=icFdIaysjFBPMJybKCZUD697ceFeAzIp7vxHH24LFrjlwZXb21LL+8MCpA0Wni+u3w ud3UuFiMIlTrn8Fn1h3wKKnnJi8Jehu0NY7N/KoK9HY3zE/ekbImxetKxZAglqFb3ijm UmINzIA9aBOOGbzhUKc+3G8hH2ZUmKD0kAtYc= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=P7frrxv1EmOfr2DcZFOflYAo4HsU6n88p4VgJqX7K7s=; b=mKmlz3mB8Z6ux4f7LylwQwKQqvargsQ5VTs92NFN7bn2bumKMe1HoxJ1641LmHlmd8 ednZlTFzqV/wyDlulAz4kF75+lGH6CNFAh178IPgZsFjXOTwxkwcMiBq3/n40htjPRjm +h3kJZswi/VqqIbLktFgGGCuqMtoZSvt/IUVJOKTinJmtNPxmuY0rwXFIxp/dWnVtXtP DdJHLWShueVfevHW28pSfJDW1/UE/mAUICbtP3ZnkVDaxwRunqQtSJoDjcNiClKvKFSQ lh161yYOXS7nzg6Xg/3f+z6wrlmbvrH5TbWeQOUr78mgHLg2/b2bAemJa8O8BARR1TwZ judQ== X-Gm-Message-State: AN3rC/5z2itLtHa6Dm/RexOMeqo/L49RVkwJ7BiezJ6cG9SR+GHwd6pi hvebaThgo2Bnc/dw X-Received: by 10.223.142.135 with SMTP id q7mr2584094wrb.180.1492967445377; Sun, 23 Apr 2017 10:10:45 -0700 (PDT) Received: from localhost.localdomain (xd93ddc2d.cust.hiper.dk. [217.61.220.45]) by smtp.gmail.com with ESMTPSA id 58sm2803521edz.2.2017.04.23.10.10.44 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Sun, 23 Apr 2017 10:10:44 -0700 (PDT) From: Christoffer Dall To: Paolo Bonzini , =?UTF-8?q?Radim=20Kr=C4=8Dm=C3=A1=C5=99?= Cc: Marc Zyngier , kvmarm@lists.cs.columbia.edu, kvm@vger.kernel.org, linux-arm-kernel@lists.infradead.org, Christoffer Dall Subject: [PULL 69/79] arm/arm64: Add hyp-stub API documentation Date: Sun, 23 Apr 2017 19:09:19 +0200 Message-Id: <20170423170929.27334-70-cdall@linaro.org> X-Mailer: git-send-email 2.9.0 In-Reply-To: <20170423170929.27334-1-cdall@linaro.org> References: <20170423170929.27334-1-cdall@linaro.org> Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Marc Zyngier 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 Acked-by: Catalin Marinas Signed-off-by: Marc Zyngier Signed-off-by: Christoffer Dall --- 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.