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: 9695177 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 7010A601E9 for ; Sun, 23 Apr 2017 17:35:29 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 6DD61209D8 for ; Sun, 23 Apr 2017 17:35:29 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 6192526530; Sun, 23 Apr 2017 17:35:29 +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=-1.9 required=2.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID autolearn=unavailable version=3.3.1 Received: from bombadil.infradead.org (bombadil.infradead.org [65.50.211.133]) (using TLSv1.2 with cipher AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id C6D13209D8 for ; Sun, 23 Apr 2017 17:35:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20170209; h=Sender: Content-Transfer-Encoding:Content-Type:MIME-Version:Cc:List-Subscribe: List-Help:List-Post:List-Archive:List-Unsubscribe:List-Id:References: In-Reply-To:Message-Id:Date:Subject:To:From:Reply-To:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:List-Owner; bh=4GGAkZEbHo0H9v8oU1QpE86f2E9+TpW1t5ojzkiLYFE=; b=W6toncNGEF+GonxzuWIRm726BS 784yi5xjDpnj66uqOs+YqqBqY5kNugnPKYlm22GjLG4IYFmQrFhmz0ujngz7fCkjdel3zfD+ZvLSD 3W/oaOCv5dkTiEspouKB1nPpUnwKRqaDSfzOFUHGLPiquO73A9GLdo6CA0JZeyJptYq5Ad6KEk3SC B2eJTwD32Jqc7xJYb5HJWWHLd06bJHGLT7YM2HtEy3elg0A/HjzX/LLO1bm4fXSn1CpVBppDSF4/Q sX/a4KcKBxPQQJxPSsDeiPER0uqHSTD3W4iC7QQaMyI6skrkTUdIdmz3tOqQ8nRuqEclZAm5opeeq EUXpa12w==; Received: from localhost ([127.0.0.1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.87 #1 (Red Hat Linux)) id 1d2LPs-0000WR-Uq; Sun, 23 Apr 2017 17:35:20 +0000 Received: from merlin.infradead.org ([2001:4978:20e::2]) by bombadil.infradead.org with esmtps (Exim 4.87 #1 (Red Hat Linux)) id 1d2LMN-0002ZO-UU for linux-arm-kernel@bombadil.infradead.org; Sun, 23 Apr 2017 17:31:44 +0000 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=merlin.20170209; h=References:In-Reply-To:Message-Id:Date: Subject:Cc:To:From:Sender:Reply-To:MIME-Version:Content-Type: Content-Transfer-Encoding:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id: List-Help:List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=P7frrxv1EmOfr2DcZFOflYAo4HsU6n88p4VgJqX7K7s=; b=o3hlNQAKDV8Vl/gAtoP6KdThl HFCZn7jWPhRQOXSIj0GeoAH+pu5Cb1A/sDZjw9aTOnM+Ou3ApxbvWolX8BcBeIvUWJ3eDJ49incMW H+g/3O2Y6NpgD7l8OA7QxBqkDtDQ9nlat8kb68VlYn9Fj9rpv4LlL//hYCakwQdKHVK0owPPyzPOR R/cMn4SSOCWWcrE7kuYfG87GKsw4sgfgM0Bg537tq1ipRLS/C0OUAAY8ggJ4NXMSYB+F/USPAsgRT ojB1XVCxR5gFziNHJ8UblNvEZYfhmV8e1Yu/7CdoZYEX7lJkq7N1saGlSu/duRUAlWu6iueii/n7a ekm+FYmkg==; Received: from mail-wr0-x230.google.com ([2a00:1450:400c:c0c::230]) by merlin.infradead.org with esmtps (Exim 4.87 #1 (Red Hat Linux)) id 1d2L2R-0005GA-J7 for linux-arm-kernel@lists.infradead.org; Sun, 23 Apr 2017 17:11:08 +0000 Received: by mail-wr0-x230.google.com with SMTP id l50so5313860wrc.3 for ; Sun, 23 Apr 2017 10:10:47 -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=LlBMpIoZrkMp9khzbxiE4qUsgvUl818hgyayHncIywG+BP6pde5/iTFm2uPQWrBRNm yaJKEdX8VP70YXf+C+atJJrrHh3r+H6YZ/MQQD0gYCfx26r6+ALE2FfvN7wzAdGHGy7G ztq5+qnl1hQz3A8eROCQyo2k81NAYZC6mPvclc7IX0rvEDCHb/i3RZe5CpakmkkzoawO bpygu6ydsoAvvJJIfI+Bc8VIN2PKCG0jZqtUKpSbpGLJ1fs2a17+ocJmNIUqEJOGX9y5 jYu7bL4uCLJdw9p0SA9DcnOVxsXDKpkc08OoJY0VkgKqojDvDETe2pYwvKHv8Hcc3KGX no+Q== X-Gm-Message-State: AN3rC/6Ru8InJCpQRCZtdp7j59xXvWYL3CNNdqQM0L9KM/xkfjBnPT9e NuHVnc5+jsFMoDkydc7nvQ== 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?= 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> X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20170423_131107_768872_4D4CCF61 X-CRM114-Status: GOOD ( 18.54 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Marc Zyngier , Christoffer Dall , kvmarm@lists.cs.columbia.edu, kvm@vger.kernel.org, linux-arm-kernel@lists.infradead.org MIME-Version: 1.0 Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+patchwork-linux-arm=patchwork.kernel.org@lists.infradead.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.