From nobody Mon Nov 25 23:39:31 2024 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 6B0871B4F1F for ; Wed, 23 Oct 2024 12:45:22 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=170.10.133.124 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729687524; cv=none; b=Xd/SBkXUJuVMU8nzi/nsVbnX+uW2bfikJiY6Gk2ZqVgRltx2aRJ4/aMIXFhRq/oGheJMI+QhyHlk2rBwSBabyz7xgjFU4tAPKupDkw1ztiDSqHfU7ruE+HWqRDc4d2331zhjcT0zn28SIX5iDx7ufvVADLtNs2Johux9hK4c+A4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729687524; c=relaxed/simple; bh=wcnFMlPKB38pGPmcyUweJksVVSBd1q5ySa95xBfPZro=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=t8FIPrh4QMF66iUFcBasbaV9xA1mIdKfb2v5OqajAfF3sO7BPSAkUjx5yPcPL/ljmzFLhihkTZOLryPUTpO1A+dDLvNsXPG/BifoSL0Galqh/teEWh+DYHhq4VU+r/FqO3pf15kQxCGbPTc+ytgpkhGvs2KJoOqYGEVTMMcNuiQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=redhat.com; spf=pass smtp.mailfrom=redhat.com; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b=ZZAMUAfz; arc=none smtp.client-ip=170.10.133.124 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=redhat.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="ZZAMUAfz" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1729687521; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=JkyMAXuhji9sRwJ3VwBSUd2i/Ce99Dz+9EW9yh0eKi0=; b=ZZAMUAfzvi1waNjU7u9ym3AxKzJu0Qz6eaDpZ1MTVhbaVqBTzmjPtIy2qpV3jfkRjPT8jk Gw7/2an4ghSrOhQTxVj2718QioqUnduKmxzgn7l8aoS7ZEZu01FI1AoYzk+Ta7Z9Umcexl dx5nInDPA/biUKaOerx0zxtuVJJHcKg= Received: from mail-wm1-f71.google.com (mail-wm1-f71.google.com [209.85.128.71]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-278-BQNNqu2vOdWnL9qSV4SDjw-1; Wed, 23 Oct 2024 08:45:19 -0400 X-MC-Unique: BQNNqu2vOdWnL9qSV4SDjw-1 Received: by mail-wm1-f71.google.com with SMTP id 5b1f17b1804b1-4316138aff6so44435605e9.1 for ; Wed, 23 Oct 2024 05:45:17 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729687515; x=1730292315; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=JkyMAXuhji9sRwJ3VwBSUd2i/Ce99Dz+9EW9yh0eKi0=; b=fPMWt7a+Up2D5K/M5+OrzNn3G8DWssfqwsZNeucxNN5xJU4bFNW7epMQDZCCis2MFc Vi46Qfcky3/vNFGUELU0Ocgc+he5Kk3Ktr0aL8GomNmV4JIaurxLv/o/rIc/ZJc/LaJO vldjJc9MfzgGCACtdMGsGWbMa8jcfIB/YN9NDHdynlaL2oVghwB8F3eYL5lDfId4AY8h 1Botfdt9ddgMOAi88Hd/rh1Q9uTEeQ9S74PTCpCJNy+JDh+hcl3XwlVmaOP9qKYkcrhi NzDF0c3fCMsu0ADzzOv9AfFShHwpfq73l4SuTjrhQa1m9LluIUy980K63CrTrGp99eFS Fd/A== X-Gm-Message-State: AOJu0YxHvudkEEx3WJQBpH96XvaQ6cbV1t+ybd8Aq0Omk4qXXCNUMRD/ 9M2kdKQmNUQq/Z7xge0nQyw6jiQBvSgJEfYCDqL1PJ4AXWXArZ5ZePonlgGUvPN5oRYj/sivXTC 0WwAq0pVdhK4WjUfT0bQUyNJM8LnvTCuOXi+vxU9Kn2ocV8/yDRRpeBPene2M2WQRG/Zqu1Bdwt NPchA2NFE7IbivU9FDEgw75UtF1HPbK6NA5hnqdqwtLN6PpJ25 X-Received: by 2002:a5d:58e9:0:b0:37d:5359:1ec1 with SMTP id ffacd0b85a97d-37efcfb1491mr1473832f8f.57.1729687515424; Wed, 23 Oct 2024 05:45:15 -0700 (PDT) X-Google-Smtp-Source: AGHT+IHtbNqS0ecvkDcNz7iJe7I/riHjsiQTeDSmBGIhAHtlSe5BNLZ7H2o+AIOEiWX20qdI1B3+xg== X-Received: by 2002:a5d:58e9:0:b0:37d:5359:1ec1 with SMTP id ffacd0b85a97d-37efcfb1491mr1473800f8f.57.1729687514946; Wed, 23 Oct 2024 05:45:14 -0700 (PDT) Received: from avogadro.local ([151.95.144.54]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-37ee0b9432fsm8825149f8f.83.2024.10.23.05.45.13 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 23 Oct 2024 05:45:13 -0700 (PDT) From: Paolo Bonzini To: linux-kernel@vger.kernel.org, kvm@vger.kernel.org Cc: roy.hopkins@suse.com, seanjc@google.com, michael.roth@amd.com, ashish.kalra@amd.com, jroedel@suse.de, thomas.lendacky@amd.com, nsaenz@amazon.com, anelkz@amazon.de, oliver.upton@linux.dev, isaku.yamahata@intel.com, maz@kernel.org, steven.price@arm.com, kai.huang@intel.com, rick.p.edgecombe@intel.com, James.Bottomley@HansenPartnership.com Subject: [RFC PATCH 1/5] KVM: powerpc: remove remaining traces of KVM_CAP_PPC_RMA Date: Wed, 23 Oct 2024 14:45:03 +0200 Message-ID: <20241023124507.280382-2-pbonzini@redhat.com> X-Mailer: git-send-email 2.46.2 In-Reply-To: <20241023124507.280382-1-pbonzini@redhat.com> References: <20241023124507.280382-1-pbonzini@redhat.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" This was only needed for PPC970 support, which is long gone: the implementation was removed in 2014. Signed-off-by: Paolo Bonzini --- Documentation/virt/kvm/api.rst | 36 ---------------------------------- arch/powerpc/kvm/powerpc.c | 3 --- 2 files changed, 39 deletions(-) diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 8e5dad80b337..85dc04bfad3b 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -2170,42 +2170,6 @@ userspace update the TCE table directly which is use= ful in some circumstances. =20 =20 -4.63 KVM_ALLOCATE_RMA ---------------------- - -:Capability: KVM_CAP_PPC_RMA -:Architectures: powerpc -:Type: vm ioctl -:Parameters: struct kvm_allocate_rma (out) -:Returns: file descriptor for mapping the allocated RMA - -This allocates a Real Mode Area (RMA) from the pool allocated at boot -time by the kernel. An RMA is a physically-contiguous, aligned region -of memory used on older POWER processors to provide the memory which -will be accessed by real-mode (MMU off) accesses in a KVM guest. -POWER processors support a set of sizes for the RMA that usually -includes 64MB, 128MB, 256MB and some larger powers of two. - -:: - - /* for KVM_ALLOCATE_RMA */ - struct kvm_allocate_rma { - __u64 rma_size; - }; - -The return value is a file descriptor which can be passed to mmap(2) -to map the allocated RMA into userspace. The mapped area can then be -passed to the KVM_SET_USER_MEMORY_REGION ioctl to establish it as the -RMA for a virtual machine. The size of the RMA in bytes (which is -fixed at host kernel boot time) is returned in the rma_size field of -the argument structure. - -The KVM_CAP_PPC_RMA capability is 1 or 2 if the KVM_ALLOCATE_RMA ioctl -is supported; 2 if the processor requires all virtual machines to have -an RMA, or 1 if the processor can use an RMA but doesn't require it, -because it supports the Virtual RMA (VRMA) facility. - - 4.64 KVM_NMI ------------ =20 diff --git a/arch/powerpc/kvm/powerpc.c b/arch/powerpc/kvm/powerpc.c index 961aadc71de2..a7e5bc0d969f 100644 --- a/arch/powerpc/kvm/powerpc.c +++ b/arch/powerpc/kvm/powerpc.c @@ -612,9 +612,6 @@ int kvm_vm_ioctl_check_extension(struct kvm *kvm, long = ext) r =3D 8 | 4 | 2 | 1; } break; - case KVM_CAP_PPC_RMA: - r =3D 0; - break; case KVM_CAP_PPC_HWRNG: r =3D kvmppc_hwrng_present(); break; --=20 2.46.2 From nobody Mon Nov 25 23:39:31 2024 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id B09631BBBDD for ; Wed, 23 Oct 2024 12:45:23 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=170.10.133.124 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729687525; cv=none; b=fy2/M1X0s8citE2ZT3z0Du9jZ+Y/cg9APiZ3OnFwyLEhvQK1dVV5Fp6T+pkhoCIhkOu365LGLnrMXdcxtOg4Gco+8WRfNkRu3HQFnImuFs3Z0OSmzXWpH03+5WPmgG9LIu5bZ5JABrRr72xsVW0IkF8XW9GNoTIDP0Ai7S/oB6Q= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729687525; c=relaxed/simple; bh=n6JPq6feOOxq4qvR2QYPYddN4qFZswV+XGRZJmKdXtI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=cfX5iFa64RDN313GWpQpVh42gl9F6OAEGoXVIhgdbFUX/0tB5beXAv8D+44N/6ZzgVPqP3eSWxcZ7SJ6WQQJuPxqZ3OHRQyxTve/teJy21T60j6tye7bD7S884zpHqY7YkNgKvEOdOYXSkXq0SpzpERs7VxnW2OFC4xOOXXwRo8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=redhat.com; spf=pass smtp.mailfrom=redhat.com; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b=jJpUXazb; arc=none smtp.client-ip=170.10.133.124 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=redhat.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="jJpUXazb" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1729687522; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=a2ui8XgastR4FaJaNRkMjtjACkKRZ87hrIJU0Aq8EZo=; b=jJpUXazbPAzqHuNPifza6FGVhUDRlJ0t73I0MS8yWcv0ruhH7lNFOALN0+VHFTYMIQIvW8 x0derHnHdPiY2EaWjzBdFkFLqny0iDwFf7mR+Z+KBaz/4TKLBLMH9S8apzQnYDXZKyrNk4 FZbec1enGt4eSWSpLJYW04kZO61ZD4c= Received: from mail-wr1-f69.google.com (mail-wr1-f69.google.com [209.85.221.69]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-482-UWwkFVq7M4e-LY2_AHKZUQ-1; Wed, 23 Oct 2024 08:45:21 -0400 X-MC-Unique: UWwkFVq7M4e-LY2_AHKZUQ-1 Received: by mail-wr1-f69.google.com with SMTP id ffacd0b85a97d-37d59ad50f3so2988113f8f.0 for ; Wed, 23 Oct 2024 05:45:20 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729687519; x=1730292319; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=a2ui8XgastR4FaJaNRkMjtjACkKRZ87hrIJU0Aq8EZo=; b=sub+CgWJla5slnCzkQ6cBiGd2KxIu0xY06zglJgYAE8e9P5oiG8efJK9M8cpOMCbyx jMt15FbSgYffHYj1vx+2/oHKlrBYJ3WhFoWByLvFKHx0A35+pikT3wi/zHcwAKyreyRW XyiS+u786hd+Z0UdcaQza3EG80rrU8sHxs/DkgK+AjYYDHgLTocwOBkc+Xkj1bBj++il /Lzky4hZqftk4WrwFJZNdZTzgIE5xjbqvXxds6FfONUFAtfd6UEv6FW/PtzLnEgOQEwD JexjP78/3yhYYyh1NTI71GrhLvaainFzbwLvTOv7RJsABSgBw7vAkgARDfQthdA6t2Zp LGYg== X-Gm-Message-State: AOJu0Ywum1tCE8OvYkavSgwNiysR40Gg544ikNu+mfx5opWIEyzTQtu5 AOMQbuxI+tWvOX2BdM70pPN6XeZz6FLPlOZoyGrPUvxbVPR5haCy60OXYcPPs9EAX7JONUDhOEC c+NhWIvJSMpNo4AdS3O3ylTmMeEqnzoGGWh/fEvtjVo5IKRVYnTCKcK9IW0Cx7PXlAws81EMxOw RR425Btm3a3q+88ZnN9BYpk37Os7YG9KDIQ4LIGYRiFIZkBZpP X-Received: by 2002:a05:600c:524a:b0:431:12d0:746b with SMTP id 5b1f17b1804b1-431841af63amr16478095e9.35.1729687518703; Wed, 23 Oct 2024 05:45:18 -0700 (PDT) X-Google-Smtp-Source: AGHT+IF0y1BXfPNku3lR35r76dw3XeTpiKZ5deNjUOi+WQ7BpuyYKJNKoHPylKmCWZZUAZbM7FLXSA== X-Received: by 2002:a05:600c:524a:b0:431:12d0:746b with SMTP id 5b1f17b1804b1-431841af63amr16477735e9.35.1729687518246; Wed, 23 Oct 2024 05:45:18 -0700 (PDT) Received: from avogadro.local ([151.95.144.54]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-43186c3a5b4sm15391805e9.38.2024.10.23.05.45.17 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 23 Oct 2024 05:45:17 -0700 (PDT) From: Paolo Bonzini To: linux-kernel@vger.kernel.org, kvm@vger.kernel.org Cc: roy.hopkins@suse.com, seanjc@google.com, michael.roth@amd.com, ashish.kalra@amd.com, jroedel@suse.de, thomas.lendacky@amd.com, nsaenz@amazon.com, anelkz@amazon.de, oliver.upton@linux.dev, isaku.yamahata@intel.com, maz@kernel.org, steven.price@arm.com, kai.huang@intel.com, rick.p.edgecombe@intel.com, James.Bottomley@HansenPartnership.com Subject: [RFC PATCH 2/5] Documentation: kvm: fix a few mistakes Date: Wed, 23 Oct 2024 14:45:04 +0200 Message-ID: <20241023124507.280382-3-pbonzini@redhat.com> X-Mailer: git-send-email 2.46.2 In-Reply-To: <20241023124507.280382-1-pbonzini@redhat.com> References: <20241023124507.280382-1-pbonzini@redhat.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" The only occurrence "Capability: none" actually meant the same as "basic". Fix that and a few more aesthetic or content issues in the document. Signed-off-by: Paolo Bonzini --- Documentation/virt/kvm/api.rst | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 85dc04bfad3b..480ab8174e56 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -96,12 +96,9 @@ description: Capability: which KVM extension provides this ioctl. Can be 'basic', which means that is will be provided by any kernel that supports - API version 12 (see section 4.1), a KVM_CAP_xyz constant, which + API version 12 (see section 4.1), or a KVM_CAP_xyz constant, which means availability needs to be checked with KVM_CHECK_EXTENSION - (see section 4.4), or 'none' which means that while not all kernels - support this ioctl, there's no capability bit to check its - availability: for kernels that don't support the ioctl, - the ioctl returns -ENOTTY. + (see section 4.4). =20 Architectures: which instruction set architectures provide this ioctl. @@ -338,8 +335,8 @@ KVM_S390_SIE_PAGE_OFFSET in order to obtain a memory ma= p of the virtual cpu's hardware control block. =20 =20 -4.8 KVM_GET_DIRTY_LOG (vm ioctl) --------------------------------- +4.8 KVM_GET_DIRTY_LOG +--------------------- =20 :Capability: basic :Architectures: all @@ -1298,7 +1295,7 @@ See KVM_GET_VCPU_EVENTS for the data structure. =20 :Capability: KVM_CAP_DEBUGREGS :Architectures: x86 -:Type: vm ioctl +:Type: vcpu ioctl :Parameters: struct kvm_debugregs (out) :Returns: 0 on success, -1 on error =20 @@ -1320,7 +1317,7 @@ Reads debug registers from the vcpu. =20 :Capability: KVM_CAP_DEBUGREGS :Architectures: x86 -:Type: vm ioctl +:Type: vcpu ioctl :Parameters: struct kvm_debugregs (in) :Returns: 0 on success, -1 on error =20 @@ -2116,8 +2113,8 @@ TLB, prior to calling KVM_RUN on the associated vcpu. =20 The "bitmap" field is the userspace address of an array. This array consists of a number of bits, equal to the total number of TLB entries as -determined by the last successful call to KVM_CONFIG_TLB, rounded up to the -nearest multiple of 64. +determined by the last successful call to ``KVM_ENABLE_CAP(KVM_CAP_SW_TLB)= ``, +rounded up to the nearest multiple of 64. =20 Each bit corresponds to one TLB entry, ordered the same as in the shared T= LB array. @@ -3554,6 +3551,27 @@ Errors: This ioctl returns the guest registers that are supported for the KVM_GET_ONE_REG/KVM_SET_ONE_REG calls. =20 +Note that s390 does not support KVM_GET_REG_LIST for historical reasons +(read: nobody cared). The set of registers in kernels 4.x and newer is: + +- KVM_REG_S390_TODPR + +- KVM_REG_S390_EPOCHDIFF + +- KVM_REG_S390_CPU_TIMER + +- KVM_REG_S390_CLOCK_COMP + +- KVM_REG_S390_PFTOKEN + +- KVM_REG_S390_PFCOMPARE + +- KVM_REG_S390_PFSELECT + +- KVM_REG_S390_PP + +- KVM_REG_S390_GBEA + =20 4.85 KVM_ARM_SET_DEVICE_ADDR (deprecated) ----------------------------------------- @@ -4902,8 +4899,8 @@ Coalesced pio is based on coalesced mmio. There is li= ttle difference between coalesced mmio and pio except that coalesced pio records accesses to I/O ports. =20 -4.117 KVM_CLEAR_DIRTY_LOG (vm ioctl) ------------------------------------- +4.117 KVM_CLEAR_DIRTY_LOG +------------------------- =20 :Capability: KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 :Architectures: x86, arm64, mips @@ -5212,7 +5209,7 @@ the cpu reset definition in the POP (Principles Of Op= eration). 4.123 KVM_S390_INITIAL_RESET ---------------------------- =20 -:Capability: none +:Capability: basic :Architectures: s390 :Type: vcpu ioctl :Parameters: none @@ -6151,7 +6148,7 @@ applied. .. _KVM_ARM_GET_REG_WRITABLE_MASKS: =20 4.139 KVM_ARM_GET_REG_WRITABLE_MASKS -------------------------------------------- +------------------------------------ =20 :Capability: KVM_CAP_ARM_SUPPORTED_REG_MASK_RANGES :Architectures: arm64 --=20 2.46.2 From nobody Mon Nov 25 23:39:31 2024 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 6E63D1ADFE6 for ; Wed, 23 Oct 2024 12:45:27 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=170.10.129.124 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729687530; cv=none; b=HCJXcF7mVVsFqj+jBL2EeRWVpi1HTsABcoVH8G1WMxyo+8afYlWWh077oY556n4APi9x9yDlePHmGeLVu9PW7Y6/3AeFmtFtMc+hj/sMlCKyNN+O5dQ7KcN7rsJsabFanIjEBt+M0Es5odiVFsGmFffAuMxhcxXXTkiGPowj+9E= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729687530; c=relaxed/simple; bh=hotHQZVnoFMtyRZ6tdX6vYrrQPC51HzlczEpuc7WVAw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=nSTj9RJaRYsyDrk9tZJ4Hr4r1JvXUChHhuQ2VfIktbdCduiiaeXRVyZq8pL8yO0+v93yHZfXYm2zOfTjeyVIVDrKPURXi9ouRYKwvn7Z3MTrr12rdaclft7AJ+Oia9dAwUg4fLMz5jfdkKGzsjuPStUHjriAx0uBwTzaocfnmUU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=redhat.com; spf=pass smtp.mailfrom=redhat.com; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b=VxWYcrVc; arc=none smtp.client-ip=170.10.129.124 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=redhat.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="VxWYcrVc" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1729687526; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=9iFQ2SoxTB2E7EgmYJpFoUM8SnPrGQqTL5Y/dS2nnkc=; b=VxWYcrVc7iYJYAohH8QgGskUUH/DItnS67Sjm1ESWlAW13DsIX97uvBIGtMgKzxIm+f1Vo n++4a7y/lxS6gu3+LtTC0hD9H5lfNOHqAltC6FL15ta+oZ4mR/TVo2NGJNRkXoHg50kP1X jo/oQQSvyJ2g6cyWl4qzH3ZmCLDqRJA= Received: from mail-wr1-f72.google.com (mail-wr1-f72.google.com [209.85.221.72]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-31--Seipkk8OkmubWYqyHRY4Q-1; Wed, 23 Oct 2024 08:45:24 -0400 X-MC-Unique: -Seipkk8OkmubWYqyHRY4Q-1 Received: by mail-wr1-f72.google.com with SMTP id ffacd0b85a97d-37d5606250aso3082547f8f.2 for ; Wed, 23 Oct 2024 05:45:24 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729687522; x=1730292322; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=9iFQ2SoxTB2E7EgmYJpFoUM8SnPrGQqTL5Y/dS2nnkc=; b=ex4K7CohkX4Hrysp6b64EXLUPg3hGwWrsFl3W+sGJIIqbDp7O0v0R70cE9o9Z+mweL YpSHuDEnsmZxJZLXx4lzEG3lxZJRVn6LvQYAtZvkuH6ybGTe5R3nHHt3nxaJ398nr09P bNyRb6RQpUQn1H/9t0g5tN5zIAh+VUEQ7Z9lRTLIrz3fAbTVCVF0FUmdAdE770UK6jr9 qWztzhsBff3T55XipJBC/gUe1Q+jOOInillaEs49P+iNMSIWhoDqtchj7GyaaE2Xo3PN J8KOO9TjzjSzu0RqcMzZ9I+JBGKxPiqr0NfNYj7My52rSs5FGbJ57cGPBBgn5IEOa3fP oQmQ== X-Gm-Message-State: AOJu0YzCkvPL7c2VQfj4frhUh4FbGyTzHvvUX3RJuJlxjrnrpbr1OI6N 2FRjTvIXgmHrNBTrFEeX9pOyoTLcvFCIUxeRLOQf1zatC5jP/9aO+xbsi5yOo8Es0/bvrjHifAS aMFN3bL3I3+PGONBYTGQaycRaDiEh8izSmNnaPeRyf0YijdR7oHQkhm+fJ0qoFWIfRKccVrv6e8 U8Ftyr3XfpctODbIRZOzp7IZ4qdO2GNueMkk9w7E7hKQeXnhay X-Received: by 2002:adf:f781:0:b0:37d:4ba1:dcff with SMTP id ffacd0b85a97d-37efcf7b9d2mr1841039f8f.42.1729687522166; Wed, 23 Oct 2024 05:45:22 -0700 (PDT) X-Google-Smtp-Source: AGHT+IEFIyABl/bqJdhPDpe+7L8YUu7GDBTYFDZy4WfrGhSIwctTeKRQGKwcmhFolqtMC+Mn/LIrUw== X-Received: by 2002:adf:f781:0:b0:37d:4ba1:dcff with SMTP id ffacd0b85a97d-37efcf7b9d2mr1841004f8f.42.1729687521616; Wed, 23 Oct 2024 05:45:21 -0700 (PDT) Received: from avogadro.local ([151.95.144.54]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-43186bdeb4asm15319465e9.15.2024.10.23.05.45.20 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 23 Oct 2024 05:45:21 -0700 (PDT) From: Paolo Bonzini To: linux-kernel@vger.kernel.org, kvm@vger.kernel.org Cc: roy.hopkins@suse.com, seanjc@google.com, michael.roth@amd.com, ashish.kalra@amd.com, jroedel@suse.de, thomas.lendacky@amd.com, nsaenz@amazon.com, anelkz@amazon.de, oliver.upton@linux.dev, isaku.yamahata@intel.com, maz@kernel.org, steven.price@arm.com, kai.huang@intel.com, rick.p.edgecombe@intel.com, James.Bottomley@HansenPartnership.com Subject: [RFC PATCH 3/5] Documentation: kvm: replace section numbers with links Date: Wed, 23 Oct 2024 14:45:05 +0200 Message-ID: <20241023124507.280382-4-pbonzini@redhat.com> X-Mailer: git-send-email 2.46.2 In-Reply-To: <20241023124507.280382-1-pbonzini@redhat.com> References: <20241023124507.280382-1-pbonzini@redhat.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" In order to simplify further introduction of hyperlinks, replace explicit section numbers with rST hyperlinks. The section numbers could actually be removed now, but I'm not going to do a huge change throughout the file for an RFC... Signed-off-by: Paolo Bonzini --- Documentation/virt/kvm/api.rst | 40 ++++++++++++++++++++++++---------- 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 480ab8174e56..42030227dedd 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -96,9 +96,9 @@ description: Capability: which KVM extension provides this ioctl. Can be 'basic', which means that is will be provided by any kernel that supports - API version 12 (see section 4.1), or a KVM_CAP_xyz constant, which - means availability needs to be checked with KVM_CHECK_EXTENSION - (see section 4.4). + API version 12 (see :ref:`KVM_GET_API_VERSION `= ), + or a KVM_CAP_xyz constant that can be checked with + :ref:`KVM_CHECK_EXTENSION `. =20 Architectures: which instruction set architectures provide this ioctl. @@ -115,6 +115,8 @@ description: are not detailed, but errors with specific meanings are. =20 =20 +.. _KVM_GET_API_VERSION: + 4.1 KVM_GET_API_VERSION ----------------------- =20 @@ -243,6 +245,8 @@ This list also varies by kvm version and host processor= , but does not change otherwise. =20 =20 +.. _KVM_CHECK_EXTENSION: + 4.4 KVM_CHECK_EXTENSION ----------------------- =20 @@ -285,7 +289,7 @@ the VCPU file descriptor can be mmap-ed, including: =20 - if KVM_CAP_DIRTY_LOG_RING is available, a number of pages at KVM_DIRTY_LOG_PAGE_OFFSET * PAGE_SIZE. For more information on - KVM_CAP_DIRTY_LOG_RING, see section 8.3. + KVM_CAP_DIRTY_LOG_RING, see :ref:`KVM_CAP_DIRTY_LOG_RING`. =20 =20 4.7 KVM_CREATE_VCPU @@ -1426,6 +1430,8 @@ because of a quirk in the virtualization implementati= on (see the internals documentation when it pops into existence). =20 =20 +.. _KVM_ENABLE_CAP: + 4.37 KVM_ENABLE_CAP ------------------- =20 @@ -2560,7 +2566,7 @@ Specifically: =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D= =3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D =20 .. [1] These encodings are not accepted for SVE-enabled vcpus. See - KVM_ARM_VCPU_INIT. + :ref:`KVM_ARM_VCPU_INIT`. =20 The equivalent register content can be accessed via bits [127:0] of the corresponding SVE Zn registers instead for vcpus that have SVE @@ -5036,8 +5042,8 @@ Recognised values for feature: Finalizes the configuration of the specified vcpu feature. =20 The vcpu must already have been initialised, enabling the affected feature= , by -means of a successful KVM_ARM_VCPU_INIT call with the appropriate flag set= in -features[]. +means of a successful :ref:`KVM_ARM_VCPU_INIT ` call wi= th the +appropriate flag set in features[]. =20 For affected vcpu features, this is a mandatory step that must be performed before the vcpu is fully usable. @@ -6380,6 +6386,8 @@ the capability to be present. `flags` must currently be zero. =20 =20 +.. _kvm_run: + 5. The kvm_run structure =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 @@ -7099,11 +7107,15 @@ primary storage for certain register types. Therefo= re, the kernel may use the values in kvm_run even if the corresponding bit in kvm_dirty_regs is not s= et. =20 =20 +.. _cap_enable: + 6. Capabilities that can be enabled on vCPUs =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 There are certain capabilities that change the behavior of the virtual CPU= or -the virtual machine when enabled. To enable them, please see section 4.37. +the virtual machine when enabled. To enable them, please see +:ref:`KVM_ENABLE_CAP`. + Below you can find a list of capabilities and what their effect on the vCP= U or the virtual machine is when enabling them. =20 @@ -7312,7 +7324,7 @@ KVM API and also from the guest. sets are supported (bitfields defined in arch/x86/include/uapi/asm/kvm.h). =20 -As described above in the kvm_sync_regs struct info in section 5 (kvm_run): +As described above in the kvm_sync_regs struct info in section :ref:`kvm_r= un`, KVM_CAP_SYNC_REGS "allow[s] userspace to access certain guest registers without having to call SET/GET_*REGS". This reduces overhead by eliminating repeated ioctl calls for setting and/or getting register values. This is @@ -7358,13 +7370,15 @@ Unused bitfields in the bitarrays must be set to ze= ro. =20 This capability connects the vcpu to an in-kernel XIVE device. =20 +.. _cap_enable_vm: + 7. Capabilities that can be enabled on VMs =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 There are certain capabilities that change the behavior of the virtual -machine when enabled. To enable them, please see section 4.37. Below -you can find a list of capabilities and what their effect on the VM -is when enabling them. +machine when enabled. To enable them, please see section +:ref:`KVM_ENABLE_CAP`. Below you can find a list of capabilities and +what their effect on the VM is when enabling them. =20 The following information is provided along with the description: =20 @@ -8515,6 +8529,8 @@ guest according to the bits in the KVM_CPUID_FEATURES= CPUID leaf (0x40000001). Otherwise, a guest may use the paravirtual features regardless of what has actually been exposed through the CPUID leaf. =20 +.. _KVM_CAP_DIRTY_LOG_RING: + 8.29 KVM_CAP_DIRTY_LOG_RING/KVM_CAP_DIRTY_LOG_RING_ACQ_REL ---------------------------------------------------------- =20 --=20 2.46.2 From nobody Mon Nov 25 23:39:31 2024 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 11A361C2DC8 for ; Wed, 23 Oct 2024 12:45:31 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=170.10.133.124 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729687533; cv=none; b=OkVW3ZwUhaq+pECVpW4eOWi1ykIp7yyqrWLftGBjiRZcxFPtChc88dLNfiWL5YSMaIf5EuT2K1tJZ9T94sUoq9E8GR8PRPaOr267BPcxaR9Gyo59UUn2ESCIeg5RJi56bsRuykVlI0ExjMMoQeYAmw2JY9lXaaK0SKHv37f8SFo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729687533; c=relaxed/simple; bh=OHUadfAY5idEC7TSz4LDwKkmn9fkkEigYvmfBwhKTe4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=TzMvAsGZ2EldFpSP0BqBbiLhanR5iUMLNcciipwLnM4Omfu6v5hjO8TgdEusb/bgMvPn1zhLYh6b6pRO4bYLxAYZqqTae2lGzH+KvemiFCxQS7MEV5NYhs3VYTtn7L7QGiFx03PP6AgTNqDGEg+2nhOAxSvR/BN/OKrg9rlDlcA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=redhat.com; spf=pass smtp.mailfrom=redhat.com; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b=dkKiP0kF; arc=none smtp.client-ip=170.10.133.124 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=redhat.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="dkKiP0kF" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1729687531; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=D6Ldk9ZxsBI9HLbbe29Tg2hsE9raC94mk4mfGYYnShE=; b=dkKiP0kF5i/mCo6hnhATkbyz3oEWH7ESTummg9ZNlhLl3gjkjVa2g64DFWvdQRfnZEJSiX U4sTJrxuFM0Vjr61oOg7pH/sbpf2oEDdycgbmC0sqoCES4kLPnWcRDqkm5tseHh7qzy1ik QEiS9BzPQOrioOvnLywh6bGcpHr6sHI= Received: from mail-wm1-f71.google.com (mail-wm1-f71.google.com [209.85.128.71]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-386-TxqnHhLbPCOq8Oz3xtccPw-1; Wed, 23 Oct 2024 08:45:29 -0400 X-MC-Unique: TxqnHhLbPCOq8Oz3xtccPw-1 Received: by mail-wm1-f71.google.com with SMTP id 5b1f17b1804b1-4316655b2f1so35601825e9.0 for ; Wed, 23 Oct 2024 05:45:28 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729687527; x=1730292327; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=D6Ldk9ZxsBI9HLbbe29Tg2hsE9raC94mk4mfGYYnShE=; b=siq6M/ssjNa66pyxK6GQEKZwjBgOahW/DumxTsUjtgtz2WnsC+hppSG9Of13LxSOS9 YCxTRdp9Iub11GETmYF8LD4v7SBuw2dk0E0CYGgn4qa144nRnzKjn47GiB9D7qvHRRdS cLq9uBL0iYynpeRtadREgDfzDk4d7a21i18vyWHzwI7bZlkih7UhNSjd+SyEEOveqLry lOBrvT8NUxATQ763dx+V/oEnWfPBfSujLoh3ye7m2BWoMsmUVOQeYrK9pCOZ74rlApPE XyKtBFyOcAv6lXHJacKKs2K+kxhRTZx83uYjduprXUzC51mTDEKMGXTn9aqHe/6d+dox 17nA== X-Gm-Message-State: AOJu0YyKZycd0f+c3kRV/9259dL+KJPf0xpH8kxvkWSNJjyipFdWiitA TzpGvJaolmrGluQ0GrSrb+mZLOg1/j3sSdzyhK4cMYIoI3qTYbo5xfsdO9uAMJLtUcuOWZZqZEn 8YEiDujRzLEPaNvZcnj8T/OpcCa6ZsN3kG1JmJn31Rq61VcbnCbN9i3Fnu8I+/M5J+pO3YAlkct O+qxxfqo2PgziUuI4tyaig7KPiiZodk7++ApShC9SrmXfFBObU X-Received: by 2002:a05:600c:1c03:b0:431:40ca:ce5d with SMTP id 5b1f17b1804b1-43184189a08mr19760865e9.23.1729687526879; Wed, 23 Oct 2024 05:45:26 -0700 (PDT) X-Google-Smtp-Source: AGHT+IHymfJH/eWTCYBn2bbQIPQsPXJ5396Qyx8zrR6Gy/0RMkieb8Q1R//90hWs2ZzLK0kBKhgm6w== X-Received: by 2002:a05:600c:1c03:b0:431:40ca:ce5d with SMTP id 5b1f17b1804b1-43184189a08mr19760485e9.23.1729687526292; Wed, 23 Oct 2024 05:45:26 -0700 (PDT) Received: from avogadro.local ([151.95.144.54]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-37ee0a4864csm8847991f8f.35.2024.10.23.05.45.25 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 23 Oct 2024 05:45:25 -0700 (PDT) From: Paolo Bonzini To: linux-kernel@vger.kernel.org, kvm@vger.kernel.org Cc: roy.hopkins@suse.com, seanjc@google.com, michael.roth@amd.com, ashish.kalra@amd.com, jroedel@suse.de, thomas.lendacky@amd.com, nsaenz@amazon.com, anelkz@amazon.de, oliver.upton@linux.dev, isaku.yamahata@intel.com, maz@kernel.org, steven.price@arm.com, kai.huang@intel.com, rick.p.edgecombe@intel.com, James.Bottomley@HansenPartnership.com Subject: [RFC PATCH 4/5] Documentation: kvm: reorganize introduction Date: Wed, 23 Oct 2024 14:45:06 +0200 Message-ID: <20241023124507.280382-5-pbonzini@redhat.com> X-Mailer: git-send-email 2.46.2 In-Reply-To: <20241023124507.280382-1-pbonzini@redhat.com> References: <20241023124507.280382-1-pbonzini@redhat.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Reorganize the text to mention file descriptors as early as possible. Also mention capabilities early as they are a central part of KVM's API. Signed-off-by: Paolo Bonzini --- Documentation/virt/kvm/api.rst | 38 ++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 42030227dedd..6619098a8054 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -7,8 +7,19 @@ The Definitive KVM (Kernel-based Virtual Machine) API Docu= mentation 1. General description =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -The kvm API is a set of ioctls that are issued to control various aspects -of a virtual machine. The ioctls belong to the following classes: +The kvm API is centered around different kinds of file descriptors +and ioctls that can be issued to these file descriptors. An initial +open("/dev/kvm") obtains a handle to the kvm subsystem; this handle +can be used to issue system ioctls. A KVM_CREATE_VM ioctl on this +handle will create a VM file descriptor which can be used to issue VM +ioctls. A KVM_CREATE_VCPU or KVM_CREATE_DEVICE ioctl on a VM fd will +create a virtual cpu or device and return a file descriptor pointing to +the new resource. + +In other words, the kvm API is a set of ioctls that are issued to +different kinds of file descriptor in order to control various aspects of +a virtual machine. Depending on the file descriptor that accepts them, +ioctls belong to the following classes: =20 - System ioctls: These query and set global attributes which affect the whole kvm subsystem. In addition a system ioctl is used to create @@ -35,18 +46,19 @@ of a virtual machine. The ioctls belong to the followi= ng classes: device ioctls must be issued from the same process (address space) that was used to create the VM. =20 -2. File descriptors -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +While most ioctls are specific to one kind of file descriptor, in some +cases the same ioctl can belong to more than one class. =20 -The kvm API is centered around file descriptors. An initial -open("/dev/kvm") obtains a handle to the kvm subsystem; this handle -can be used to issue system ioctls. A KVM_CREATE_VM ioctl on this -handle will create a VM file descriptor which can be used to issue VM -ioctls. A KVM_CREATE_VCPU or KVM_CREATE_DEVICE ioctl on a VM fd will -create a virtual cpu or device and return a file descriptor pointing to -the new resource. Finally, ioctls on a vcpu or device fd can be used -to control the vcpu or device. For vcpus, this includes the important -task of actually running guest code. +The KVM API grew over time. For this reason, KVM defines many constants + of the form ``KVM_CAP_*``, each corresponding to a set of functionality +provided by one or more ioctls. Availability of these "capabilities" can +be checked with :ref:`KVM_CHECK_EXTENSION `. Some +capabilities also need to be enabled for VMs or VCPUs where their +functionality is desired (see :ref:`cap_enable` and :ref:`cap_enable_vm`). + + +2. Restrictions +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 In general file descriptors can be migrated among processes by means of fork() and the SCM_RIGHTS facility of unix domain socket. These --=20 2.46.2 From nobody Mon Nov 25 23:39:31 2024 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 8E0DF1C75F3 for ; Wed, 23 Oct 2024 12:45:35 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=170.10.133.124 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729687538; cv=none; b=dWbnGLknxLBXkqp3fZfDpEz3Hc6CV4u1XL20WzJ3BCyGI+I8bFSP2cXt7ve5NnBmZYxjLRv5se84JvNXWxW48Apdixv4w/Y2a9YvJkBxL0BCDosN41GGrD6JNx0m+7U4llSg0r3Lv3CAe4FB2CqArkiFjAqRVoDLv3Q++oQw3C8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729687538; c=relaxed/simple; bh=K/Y7csYRI3/oxlx7xO3kDMrHXFp/AihAgtRQUEmCWm0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=ot3DljZ9L8SN3RRO3ei9xl96Ef0OiPeYAwujddrsc0S+V5821g85BpR4ft9xpA13JdL0oNuyISgDYnIUd3ADEZQmquoBjCbl2tF7asLF82neHR1we8k5bRjYN4Gtt8bl8upkakgUwc7GTIqZ1w1MRPjUs+sbB12k/k+6TljNqnA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=redhat.com; spf=pass smtp.mailfrom=redhat.com; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b=fKrSRKGH; arc=none smtp.client-ip=170.10.133.124 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=redhat.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="fKrSRKGH" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1729687534; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=SPxR7C/HaEIovhverKHKQ0rL+reVbPsHUmzV/lR/YoM=; b=fKrSRKGH34Pl1JXMSTl4kBklEvyobdyPETWAIi7Oy/GjxI1i+Xi4CtIMz9YK6A37iOOl13 tDILEW0yAUNZ6a4cOnynSdtgOIABqJDyRj+iH1t3DZk/nUBj5SkwZdn5L7mz8cgq1t1qat n9xHKV22Kry9JouQPzy1tZO6dyOQ4P4= Received: from mail-wm1-f71.google.com (mail-wm1-f71.google.com [209.85.128.71]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-632-m4rOiSuSMRavyfBPO-D5jg-1; Wed, 23 Oct 2024 08:45:33 -0400 X-MC-Unique: m4rOiSuSMRavyfBPO-D5jg-1 Received: by mail-wm1-f71.google.com with SMTP id 5b1f17b1804b1-4316138aff6so44437305e9.1 for ; Wed, 23 Oct 2024 05:45:33 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729687531; x=1730292331; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=SPxR7C/HaEIovhverKHKQ0rL+reVbPsHUmzV/lR/YoM=; b=PBthAn6xmq9h6Nzf7OsDBiPpKiht7E5ks6O7y8S7iYcx2jJNl1ZwvLUCucBxUtEuqL 1MMeUPDQTATw0JkZcggiNfDGiALE1+04yZ1JnpkI75AWaoURS0/yDYTY7UrSE0Ujfg76 iL0Z4MGwG/2jTNffriWTdFN5VrPHnAnoYOqlJgrZ8dAA/1imFRV6vzLRGvFmzmhgP9LI aZlpsxLUQCD6YPjm/b9iFWhkbDEKgwUxjjA50UUDM4zTfQLkafMjTKvadFGkzOYL4+aG /vEOuniEKB0mPOesQzdqYVI8BEz0poJY0pjOUGknsOju0VJkwwvVzatW4YVGNJAHBR50 ED9w== X-Gm-Message-State: AOJu0YzQKgUIusLIpQSy3OlGPEHcdyQ8fwU4aLceMTb323b9n+WRnUt7 ToUz1cWrZHQxLHydCnpcAzFUf/vHNxbz7Ns/cdPvDszNz28OArhIin7JLE+8HLsq/N1sbt0/lTu BBIfTzJMhM9OhESQRC3EdlhGDYv9EU3YdwyK1SkDxenGoatNKnda1rXBWGJS+3bqYk3oqDSoFLG 8UvbFJaiZjdwSJMfTWIEekT9hmFvLdxrGSoi4gNLP2dKV8d3pu X-Received: by 2002:a05:600c:3d1b:b0:431:40ca:ce6e with SMTP id 5b1f17b1804b1-431841a2f84mr20455535e9.31.1729687530629; Wed, 23 Oct 2024 05:45:30 -0700 (PDT) X-Google-Smtp-Source: AGHT+IHTYFIm67sbi244UmXzIKKh5+7jpM4o3zWGaat+q+NnaNS4JnfgCwvMl4jpJLGZUJPet19/yQ== X-Received: by 2002:a05:600c:3d1b:b0:431:40ca:ce6e with SMTP id 5b1f17b1804b1-431841a2f84mr20455035e9.31.1729687529884; Wed, 23 Oct 2024 05:45:29 -0700 (PDT) Received: from avogadro.local ([151.95.144.54]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-43186bd693fsm15619655e9.2.2024.10.23.05.45.28 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 23 Oct 2024 05:45:29 -0700 (PDT) From: Paolo Bonzini To: linux-kernel@vger.kernel.org, kvm@vger.kernel.org Cc: roy.hopkins@suse.com, seanjc@google.com, michael.roth@amd.com, ashish.kalra@amd.com, jroedel@suse.de, thomas.lendacky@amd.com, nsaenz@amazon.com, anelkz@amazon.de, oliver.upton@linux.dev, isaku.yamahata@intel.com, maz@kernel.org, steven.price@arm.com, kai.huang@intel.com, rick.p.edgecombe@intel.com, James.Bottomley@HansenPartnership.com Subject: [PATCH 5/5] Documentation: kvm: introduce "VM plane" concept Date: Wed, 23 Oct 2024 14:45:07 +0200 Message-ID: <20241023124507.280382-6-pbonzini@redhat.com> X-Mailer: git-send-email 2.46.2 In-Reply-To: <20241023124507.280382-1-pbonzini@redhat.com> References: <20241023124507.280382-1-pbonzini@redhat.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" There have been multiple occurrences of processors introducing a virtual privilege level concept for guests, where the hypervisor hosts multiple copies of a vCPU's register state (or at least of most of it) and provides hypercalls or instructions to switch between them. These include AMD VMPLs, Intel TDX partitions, Microsoft Hyper-V VTLs, and ARM CCA planes. Include documentation on how the feature will be exposed to userspace, based on a draft made between Plumbers and KVM Forum. In the past, two main solutions that were attempted, mostly in the context of Hyper-V VTLs and SEV-SNP VMPLs: - use a single vCPU file descriptor, and store multiple copies of the state in a single struct kvm_vcpu. This requires a lot of changes to provide multiple copies of affected fields, especially MMUs and APICs; and complex uAPI extensions to direct existing ioctls to a specific privilege level. This solution looked marginally okay for SEV-SNP VMPLs, but only because the copies of the register state were hidden in the VMSA (KVM does not manage it); it showed all its problems when applied to Hyper-V VTLs. - use multiple VM and vCPU file descriptors, and handle the switch entirely in userspace. This got gnarly pretty fast for even more reasons than the previous case, for example because VMs could not share anymore memslots, including dirty bitmaps and private/shared attributes (a substantial problem for SEV-SNP since VMPLs share their ASID). Another problem was the need to share _some_ register state across VTLs and to control that vCPUs did not run in parallel; there needed to be a lot of logic to be added in userspace to ensure that higher-privileged VTL properly interrupted a lower-privileged one. This solution also complicates in-kernel implementation of privilege level switch, or even makes it impossible, because there is no kernel knowledge of the relationship between vCPUs that have the same id but belong to different privilege levels. Especially given the need to accelerate switches in kernel, it is clear that KVM needs some level of knowledge of the relationship between vCPUs that have the same id but belong to different privilege levels. For this reason, I proposed a design that only gives the initial set of VM and vCPU = file descriptors the full set of ioctls + struct kvm_run; other privilege levels instead only support a small part of the KVM API. In fact for the vm file descriptor it is only three ioctls: KVM_CHECK_EXTENSION, KVM_SIGNAL_MSI, KVM_SET_MEMORY_ATTRIBUTES. For vCPUs it is basically KVM_GET/SET_*. This solves a lot of the problems in the multiple-file-descriptors solution, namely it gets for free the ability to avoid parallel execution of the same vCPUs in different privilege levels. Changes to the userspace API of course exist, but they are relatively small and more easily backwards compatible, because they boil down to the introduction of new file descriptor kinds instead of having to change the inputs to all affected ioctls. It does share some of the code churn issues in the single-file-descriptor solution; on the other hand a prototype multi-fd VMPL implementation[1] also needed large scale changes which therefore seem unavoidable when privilege levels are provided by hardware, and not a software concept only as is the case for VTLs. hardware=20 [1] https://lore.kernel.org/lkml/cover.1726506534.git.roy.hopkins@suse.c= om/ Acknowledgements: thanks to everyone who participated in the discussions, you are too many to mention in a small margin. Thanks to Roy Hopkins, Tom Lendacky, Anel Orazgaliyeva, Nicolas Saenz-Julienne for experimenting with implementations of VTLs and VMPLs. Ah, and because x86 has three names for it and Arm has one, choose the Arm name for all architectures to avoid bikeshedding and to displease everyone---including the KVM/arm64 folks, probably. Signed-off-by: Paolo Bonzini --- Documentation/virt/kvm/api.rst | 224 ++++++++++++++++++++--- Documentation/virt/kvm/vcpu-requests.rst | 7 + 2 files changed, 205 insertions(+), 26 deletions(-) diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 6619098a8054..6777c24dedde 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -56,6 +56,18 @@ be checked with :ref:`KVM_CHECK_EXTENSION `. Some capabilities also need to be enabled for VMs or VCPUs where their functionality is desired (see :ref:`cap_enable` and :ref:`cap_enable_vm`). =20 +On some architectures, a "virtual privilege level" concept may be present +apart from the usual separation between user and supervisor mode, or +between hypervisor and guest mode. When this is the case, a single vCPU +can have multiple copies of its register state (or at least most of it), +and will switch between them through a special processor instruction, +or through some kind of hypercall. + +KVM calls these privilege levels "planes". Planes other than the +initially-created one (called "plane 0") have a file descriptor each, +and so do the planes of each vCPU. Ioctls for vCPU planes should also +be issued from a single thread, unless specially marked as asynchronous +in the documentation. =20 2. Restrictions =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -119,6 +131,11 @@ description: Type: system, vm, or vcpu. =20 + File descriptors for planes other than plane 0 provide a subset + of vm and vcpu ioctls. Those that *are* supported in extra + planes are marked specially in the documentation (for example, + `vcpu (all planes)`). + Parameters: what parameters are accepted by the ioctl. =20 @@ -281,7 +281,7 @@ otherwise. =20 :Capability: basic, KVM_CAP_CHECK_EXTENSION_VM for vm ioctl :Architectures: all -:Type: system ioctl, vm ioctl +:Type: system ioctl, vm ioctl (all planes) :Parameters: extension identifier (KVM_CAP_*) :Returns: 0 if unsupported; 1 (or some other positive integer) if supported =20 @@ -421,7 +438,7 @@ kvm_run' (see below). =20 :Capability: basic :Architectures: all except arm64 -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_regs (out) :Returns: 0 on success, -1 on error =20 @@ -461,7 +478,7 @@ Reads the general purpose registers from the vcpu. =20 :Capability: basic :Architectures: all except arm64 -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_regs (in) :Returns: 0 on success, -1 on error =20 @@ -475,7 +492,7 @@ See KVM_GET_REGS for the data structure. =20 :Capability: basic :Architectures: x86, ppc -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_sregs (out) :Returns: 0 on success, -1 on error =20 @@ -506,7 +523,7 @@ but not yet injected into the cpu core. =20 :Capability: basic :Architectures: x86, ppc -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_sregs (in) :Returns: 0 on success, -1 on error =20 @@ -519,7 +536,7 @@ data structures. =20 :Capability: basic :Architectures: x86 -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_translation (in/out) :Returns: 0 on success, -1 on error =20 @@ -645,7 +662,7 @@ This is an asynchronous vcpu ioctl and can be invoked f= rom any thread. =20 :Capability: basic (vcpu), KVM_CAP_GET_MSR_FEATURES (system) :Architectures: x86 -:Type: system ioctl, vcpu ioctl +:Type: system ioctl, vcpu ioctl (all planes) :Parameters: struct kvm_msrs (in/out) :Returns: number of msrs successfully returned; -1 on error @@ -685,7 +702,7 @@ kvm will fill in the 'data' member. =20 :Capability: basic :Architectures: x86 -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_msrs (in) :Returns: number of msrs successfully set (see below), -1 on error =20 @@ -773,7 +790,7 @@ signal mask. =20 :Capability: basic :Architectures: x86, loongarch -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_fpu (out) :Returns: 0 on success, -1 on error =20 @@ -811,7 +828,7 @@ Reads the floating point state from the vcpu. =20 :Capability: basic :Architectures: x86, loongarch -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_fpu (in) :Returns: 0 on success, -1 on error =20 @@ -1122,7 +1139,7 @@ Other flags returned by ``KVM_GET_CLOCK`` are accepte= d but ignored. :Capability: KVM_CAP_VCPU_EVENTS :Extended by: KVM_CAP_INTR_SHADOW :Architectures: x86, arm64 -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_vcpu_events (out) :Returns: 0 on success, -1 on error =20 @@ -1245,7 +1262,7 @@ directly to the virtual CPU). :Capability: KVM_CAP_VCPU_EVENTS :Extended by: KVM_CAP_INTR_SHADOW :Architectures: x86, arm64 -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_vcpu_events (in) :Returns: 0 on success, -1 on error =20 @@ -1311,7 +1328,7 @@ See KVM_GET_VCPU_EVENTS for the data structure. =20 :Capability: KVM_CAP_DEBUGREGS :Architectures: x86 -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_debugregs (out) :Returns: 0 on success, -1 on error =20 @@ -1333,7 +1350,7 @@ Reads debug registers from the vcpu. =20 :Capability: KVM_CAP_DEBUGREGS :Architectures: x86 -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_debugregs (in) :Returns: 0 on success, -1 on error =20 @@ -1649,7 +1666,7 @@ otherwise it will return EBUSY error. =20 :Capability: KVM_CAP_XSAVE :Architectures: x86 -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_xsave (out) :Returns: 0 on success, -1 on error =20 @@ -1669,7 +1686,7 @@ This ioctl would copy current vcpu's xsave struct to = the userspace. =20 :Capability: KVM_CAP_XSAVE and KVM_CAP_XSAVE2 :Architectures: x86 -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_xsave (in) :Returns: 0 on success, -1 on error =20 @@ -1697,7 +1714,7 @@ contents of CPUID leaf 0xD on the host. =20 :Capability: KVM_CAP_XCRS :Architectures: x86 -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_xcrs (out) :Returns: 0 on success, -1 on error =20 @@ -1724,7 +1741,7 @@ This ioctl would copy current vcpu's xcrs to the user= space. =20 :Capability: KVM_CAP_XCRS :Architectures: x86 -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_xcrs (in) :Returns: 0 on success, -1 on error =20 @@ -2014,7 +2031,7 @@ error. =20 :Capability: KVM_CAP_IRQCHIP :Architectures: x86 -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_lapic_state (out) :Returns: 0 on success, -1 on error =20 @@ -2045,7 +2062,7 @@ always uses xAPIC format. =20 :Capability: KVM_CAP_IRQCHIP :Architectures: x86 -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_lapic_state (in) :Returns: 0 on success, -1 on error =20 @@ -2296,7 +2296,7 @@ prior to calling the KVM_RUN ioctl. =20 :Capability: KVM_CAP_ONE_REG :Architectures: all -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_one_reg (in) :Returns: 0 on success, negative value on failure =20 @@ -2908,7 +2908,7 @@ such as set vcpu counter or reset vcpu, and they have= the following id bit patte =20 :Capability: KVM_CAP_ONE_REG :Architectures: all -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_one_reg (in and out) :Returns: 0 on success, negative value on failure =20 @@ -2962,7 +2962,7 @@ after pausing the vcpu, but before it is resumed. =20 :Capability: KVM_CAP_SIGNAL_MSI :Architectures: x86 arm64 -:Type: vm ioctl +:Type: vm ioctl (all planes) :Parameters: struct kvm_msi (in) :Returns: >0 on delivery, 0 if guest blocked the MSI, and -1 on error =20 @@ -3565,7 +3565,7 @@ VCPU matching underlying host. =20 :Capability: basic :Architectures: arm64, mips, riscv -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_reg_list (in/out) :Returns: 0 on success; -1 on error =20 @@ -4807,7 +4824,7 @@ The acceptable values for the flags field are:: =20 :Capability: KVM_CAP_NESTED_STATE :Architectures: x86 -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_nested_state (in/out) :Returns: 0 on success, -1 on error =20 @@ -4881,7 +4898,7 @@ to the KVM_CHECK_EXTENSION ioctl(). =20 :Capability: KVM_CAP_NESTED_STATE :Architectures: x86 -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_nested_state (in) :Returns: 0 on success, -1 on error =20 @@ -5762,7 +5779,7 @@ then ``length`` is returned. =20 :Capability: KVM_CAP_SREGS2 :Architectures: x86 -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_sregs2 (out) :Returns: 0 on success, -1 on error =20 @@ -5795,7 +5812,7 @@ flags values for ``kvm_sregs2``: =20 :Capability: KVM_CAP_SREGS2 :Architectures: x86 -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_sregs2 (in) :Returns: 0 on success, -1 on error =20 @@ -6011,7 +6028,7 @@ as the descriptors in Descriptors block. =20 :Capability: KVM_CAP_XSAVE2 :Architectures: x86 -:Type: vcpu ioctl +:Type: vcpu ioctl (all planes) :Parameters: struct kvm_xsave (out) :Returns: 0 on success, -1 on error =20 @@ -6269,7 +6286,7 @@ Returns -EINVAL if called on a protected VM. =20 :Capability: KVM_CAP_MEMORY_ATTRIBUTES :Architectures: x86 -:Type: vm ioctl +:Type: vm ioctl (all planes) :Parameters: struct kvm_memory_attributes (in) :Returns: 0 on success, <0 on error =20 @@ -6398,6 +6415,46 @@ the capability to be present. `flags` must currently be zero. =20 =20 +.. _KVM_CREATE_PLANE: + +4.144 KVM_CREATE_PLANE +---------------------- + +:Capability: KVM_CAP_PLANE +:Architectures: none +:Type: vm ioctl +:Parameters: plane id +:Returns: a VM fd that can be used to control the new plane. + +Creates a new *plane*, i.e. a separate privilege level for the +virtual machine. Each plane has its own memory attributes, +which can be used to enable more restricted permissions than +what is allowed with ``KVM_SET_USER_MEMORY_REGION``. + +Each plane has a numeric id that is used when communicating +with KVM through the :ref:`kvm_run ` struct. While +KVM is currently agnostic to whether low ids are more or less +privileged, it is expected that this will not always be the +case in the future. For example KVM in the future may use +the plane id when planes are supported by hardware (as is the +case for VMPLs in AMD), or if KVM supports accelerated plane +switch operations (as might be the case for Hyper-V VTLs). + +4.145 KVM_CREATE_VCPU_PLANE +--------------------------- + +:Capability: KVM_CAP_PLANE +:Architectures: none +:Type: vm ioctl (non default plane) +:Parameters: vcpu file descriptor for the default plane +:Returns: a vCPU fd that can be used to control the new plane + for the vCPU. + +Adds a vCPU to a plane; the new vCPU's id comes from the vCPU +file descriptor that is passed in the argument. Note that + because of how the API is defined, planes other than plane 0 +can only have a subset of the ids that are available in plane 0. + .. _kvm_run: =20 5. The kvm_run structure @@ -6433,7 +6490,50 @@ This field is ignored if KVM_CAP_IMMEDIATE_EXIT is n= ot available. =20 :: =20 - __u8 padding1[6]; + /* in/out */ + __u8 plane; + +The plane that will be run (usually 0). + +While this is not yet supported, in the future KVM may handle plane +switch in the kernel. In this case, the output value of this field +may differ from the input value. However, automatic switch will +have to be :ref:`explicitly enabled `. + +For backwards compatibility, this field is ignored unless a plane +other than plane 0 has been created. + +:: + + /* in/out */ + __u16 suspended_planes; + +A bitmap of planes whose execution was suspended to run a +higher-privileged plane, usually via a hypercall or due to +an interrupt in the higher-privileged plane. + +KVM right now does not use this field; it may be used in the future +once KVM implements in-kernel plane switch mechanisms. Until that +is the case, userspace can leave this to zero. + +:: + + /* in */ + __u16 req_exit_planes; + +A bitmap of planes for which KVM should exit when they have a pending +interrupt. In general, userspace should set bits corresponding to +planes that are more privileged than ``plane``; because KVM is agnostic +to whether low ids are more or less privileged, these could be the bits +*above* or *below* ``plane``. In some cases it may make sense to request +an exit for all planes---for example, if the higher-priority plane +wants to be informed about interrupts pending in lower-priority planes, +userspace may need to learn about those as well. + +The bit at position ``plane`` is ignored; interrupts for the current +plane are never delivered to userspace. + +:: =20 /* out */ __u32 exit_reason; @@ -7086,6 +7186,44 @@ The valid value for 'flags' is: - KVM_NOTIFY_CONTEXT_INVALID -- the VM context is corrupted and not valid in VMCS. It would run into unknown result if resume the target VM. =20 +:: + + /* KVM_EXIT_PLANE_EVENT */ + struct { + #define KVM_PLANE_EVENT_INTERRUPT 0 + __u16 pending_event_planes; + __u8 cause; + __u8 target; + __u32 flags; + __u64 extra; + } plane; + +Inform userspace of an event that affects a different plane than the +currently executing one. + +On a ``KVM_EXIT_PLANE_EVENT`` exit, ``pending_event_planes`` is always +set to the set of planes that have a pending interrupt. + +``cause`` provides the event that caused the exit, and the meaning of +``target`` depends on the cause of the exit too. + +Right now the only defined cause is ``KVM_PLANE_EVENT_INTERRUPT``, i.e. +an interrupt was received by a plane whose id is set in the +``req_exit_planes`` bitmap. In this case, ``target`` is the id of the +plane that received an interrupt, and its bit is always set in both +``req_exit_planes`` and ``pending_event_planes``. + +``flags`` and ``extra`` are currently always 0. + +If userspace wants to switch to the target plane, it should move any +shared state from the current plane to ``target``, and then invoke +``KVM_RUN`` with ``kvm_run->plane`` set to ``target`` (and +``req_exit_planes`` initialized accordingly). Note that it's also +valid to switch planes in response to other userspace exit codes, for +example ``KVM_EXIT_X86_WRMSR`` or ``KVM_EXIT_HYPERCALL``. Immediately +after ``KVM_RUN`` is entered, KVM will check ``req_exit_planes`` and +trigger a ``KVM_EXIT_PLANE_EVENT`` userspace exit if needed. + :: =20 /* Fix the size of the union. */ @@ -8930,6 +9068,40 @@ Do not use KVM_X86_SW_PROTECTED_VM for "real" VMs, a= nd especially not in production. The behavior and effective ABI for software-protected VMs is unstable. =20 +8.42 KVM_CAP_PLANE +------------------ + +:Capability: KVM_CAP_PLANE +:Architectures: x86 +:Type: system, vm + +The capability returns the maximum plane id that can be passed to +:ref:`KVM_CREATE_PLANE `. Because the maximum +id can vary according to the machine type, it is recommended to +check for this capability on the VM file descriptor. + +When called on the system file descriptor, KVM returns the highest +value supported on any machine type. + + +8.42 KVM_CAP_PLANE_FPU +---------------------- + +:Capability: KVM_CAP_PLANE_FPU +:Architectures: x86 +:Type: system, vm + +The capability returns 1 if the FPU is split for each vCPU plane. +If the capability is absent, the FPU is shared by all vCPU planes. + +Note that ioctls such as KVM_SET_XSAVE or KVM_SET_FPU *are* available +even if this capability is absent. However, they will overwrite the +registers presented to other planes. + +Also note that KVM_GET/SET_XSAVE also allows access to some registers +that are *not* part of FPU state, notably PKRU. Those are never shared. + + 9. Known KVM API problems =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D =20 diff --git a/Documentation/virt/kvm/vcpu-requests.rst b/Documentation/virt/= kvm/vcpu-requests.rst index 06718b9bc959..86ac67b98a74 100644 --- a/Documentation/virt/kvm/vcpu-requests.rst +++ b/Documentation/virt/kvm/vcpu-requests.rst @@ -286,6 +286,13 @@ architecture dependent. kvm_vcpu_block() calls kvm_ar= ch_vcpu_runnable() to check if it should awaken. One reason to do so is to provide architectures a function where requests may be checked if necessary. =20 +VM planes +--------- + +Each plane has its own set of requests. Processing requests from +another plane needs to go through a plane switch, for example via a +`KVM_EXIT_PLANE_EVENT` userspace exit. + References =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 --=20 2.46.2