From nobody Sun Feb 8 23:03:55 2026 Received: from mail-vk1-f202.google.com (mail-vk1-f202.google.com [209.85.221.202]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 257EE20766B for ; Wed, 4 Dec 2024 19:14:29 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.221.202 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1733339671; cv=none; b=Fd/Ta6enpBGiljX1LSQYDIPOjV4xVxFViPYe02iYuP8n/37OzqmX1SWnv7PRpNED/w5+Kl6/AsierBIBCbK5Q2JXpYjTP+lzAcvqLX8dBX/m+TfEvW0qoeusnfPLJpZtEnSbZacDHvkB7nuNXneqwqi+KlMkITON74++INTAMyo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1733339671; c=relaxed/simple; bh=y+38ZRGskOv31V+pgdRIkwmafpiX8dTbP5MleVcleIA=; h=Date:In-Reply-To:Mime-Version:References:Message-ID:Subject:From: To:Cc:Content-Type; b=fUSDsIzuJSbhJKF1UPSB5o8iY0KALN5jpRyYnMAjM2sA+4RzYYxgLR/8aqRPtcHKJCVEGYpZNqFVn9/tS5iQ8uYAqGvq1oXXvKnfPi7Yy+yAneGwzprPdKf2oE+PhCRJVQwLvka9IcDYhWM3btytr/Q6dhsnsNSQQ1ABrV5wAS0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com; spf=pass smtp.mailfrom=flex--jthoughton.bounces.google.com; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b=FBuI28B4; arc=none smtp.client-ip=209.85.221.202 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=flex--jthoughton.bounces.google.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b="FBuI28B4" Received: by mail-vk1-f202.google.com with SMTP id 71dfb90a1353d-515d07b1251so54680e0c.0 for ; Wed, 04 Dec 2024 11:14:28 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1733339668; x=1733944468; darn=vger.kernel.org; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:from:to:cc:subject:date:message-id:reply-to; bh=FVmBABSFHx5R5MTquILKgGxl08w4PCC+wHr0khmGJK8=; b=FBuI28B4NDrWfXhTzQ+6m8w84pt07w9suq78em60NLM/LT7nTEyZjbCmSo2VyCePqR 2uReS+ko94MUqS3lJ9OcV0q47P2YSO3iG2R4QrkX5Xz6p03LX8WKIz/c4NcqLyWZ24ZD wUhwDT3AXmLhxp2Gk+Oq2jVhvS5u4KBKClzXUBjvxafmDAZ3RwZD3Z7ZzppjOp/Jc/p3 LEHjroTg1WDzuIt2Mvm3ShqxEqK6y8OQxNRsTSxRWeOGV9z9AUIsiZlEhOeKkb/rhmt/ ijW70E0V/VEkY5qrfw2ys68fr2G6qRN6sqF5aF+S7X4FaPOIDMdgVEUaC0uDl2WcStE+ tA2Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1733339668; x=1733944468; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=FVmBABSFHx5R5MTquILKgGxl08w4PCC+wHr0khmGJK8=; b=TYtcU5IYboVJTh/TdNxQpn4kEDqTzUbk77PHkxzteHNkQp3k/Mh+ItO79zBssbsLio UpPsEIEMcxmjzgF1xCtcOscHCrVKjdoZ3Li2SZOU4XBJ5l7W1JlGe8CpC2XM8DTMuHgW mc9f1D0K0ubi5G3nL8FJDt8CEpUwINEQV4PG5B1kJe0E6WGzv+7Q4lb2ijEFkHirCe/y hH/6Sgqnn3hyLO3iimLb0i5XS4PsdxdnJX7jbLxn6N+aYBSavk0qtnk6SY1peT6ftFkv DUhJpgc6PlqV1xN1hByp2mhUMxQcXMi79zOSksgOd7Zz0ir03tDvGHDNuE3isNajJyji cZwQ== X-Forwarded-Encrypted: i=1; AJvYcCUDlQvnVZls+ZCPYc1WhpfIt7y8ECG/qIiJ1ra0fnrXtBHS/x3Sg4dv1sD3XO43b+fmln4UrjG7Z2/qsWI=@vger.kernel.org X-Gm-Message-State: AOJu0YzcWDP2u57Gl1GCuYwe2VfyxzLcnJQ7j5pkdnCh1onA+EX0dTIz 3cjalSbvhE9ILF6DQaPhNYO4SqzOPczVARvK7MEzfxLZGjZi5tZFQwRn/4MYHpHkZhdeyTmo1d+ 2rplg+bvnXS/xdEkVwQ== X-Google-Smtp-Source: AGHT+IH+tCG51tTfToGtalOfr4jm1GPLIEdYYz0WZu1LFU6o/sXkUUif2KKj20JmKczb7eMhosGsEIxjk4+0fihs X-Received: from vkbfs3.prod.google.com ([2002:a05:6122:3b83:b0:50d:9196:e944]) (user=jthoughton job=prod-delivery.src-stubby-dispatcher) by 2002:a05:6122:4203:b0:515:26e7:736 with SMTP id 71dfb90a1353d-515bf307c0emr11029687e0c.6.1733339668025; Wed, 04 Dec 2024 11:14:28 -0800 (PST) Date: Wed, 4 Dec 2024 19:13:48 +0000 In-Reply-To: <20241204191349.1730936-1-jthoughton@google.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: Mime-Version: 1.0 References: <20241204191349.1730936-1-jthoughton@google.com> X-Mailer: git-send-email 2.47.0.338.g60cca15819-goog Message-ID: <20241204191349.1730936-14-jthoughton@google.com> Subject: [PATCH v1 13/13] KVM: Documentation: Add KVM_CAP_USERFAULT and KVM_MEM_USERFAULT details From: James Houghton To: Paolo Bonzini , Sean Christopherson Cc: Jonathan Corbet , Marc Zyngier , Oliver Upton , Yan Zhao , James Houghton , Nikita Kalyazin , Anish Moorthy , Peter Gonda , Peter Xu , David Matlack , Wang@google.com, Wei W , kvm@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-arm-kernel@lists.infradead.org, kvmarm@lists.linux.dev Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Include the note about memory ordering when clearing bits in userfault_bitmap, as it may not be obvious for users. Signed-off-by: James Houghton Reviewed-by: Bagas Sanjaya --- I would like to include the new -EFAULT reason in the documentation for KVM_RUN (the case where userfault_bitmap could not be read), as -EFAULT usually means that GUP failed. --- Documentation/virt/kvm/api.rst | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 454c2aaa155e..eec485dcf0bc 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -6281,7 +6281,8 @@ bounds checks apply (use common sense). __u64 guest_memfd_offset; __u32 guest_memfd; __u32 pad1; - __u64 pad2[14]; + __u64 userfault_bitmap; + __u64 pad2[13]; }; =20 A KVM_MEM_GUEST_MEMFD region _must_ have a valid guest_memfd (private memo= ry) and @@ -6297,6 +6298,25 @@ state. At VM creation time, all memory is shared, i= .e. the PRIVATE attribute is '0' for all gfns. Userspace can control whether memory is shared/priva= te by toggling KVM_MEMORY_ATTRIBUTE_PRIVATE via KVM_SET_MEMORY_ATTRIBUTES as nee= ded. =20 +When the KVM_MEM_USERFAULT flag is set, userfault_bitmap points to the sta= rting +address for the bitmap that controls if vCPU memory faults should immediat= ely +exit to userspace. If an invalid pointer is provided, at fault time, KVM_R= UN +will return -EFAULT. KVM_MEM_USERFAULT is only supported when +KVM_CAP_USERFAULT is supported. + +userfault_bitmap should point to an array of longs where each bit in the a= rray +linearly corresponds to a single gfn. Bit 0 in userfault_bitmap correspond= s to +guest_phys_addr, bit 1 corresponds to guest_phys_addr + PAGE_SIZE, etc. If= the +bit for a page is set, any vCPU access to that page will exit to userspace= with +KVM_MEMORY_EXIT_FLAG_USERFAULT. + +Setting bits in userfault_bitmap has no effect on pages that have already = been +mapped by KVM until KVM_MEM_USERFAULT is disabled and re-enabled again. + +Clearing bits in userfault_bitmap should usually be done with a store-rele= ase +if changes to guest memory are being made available to the guest via +userfault_bitmap. + S390: ^^^^^ =20 @@ -8251,6 +8271,17 @@ KVM exits with the register state of either the L1 o= r L2 guest depending on which executed at the time of an exit. Userspace must take care to differentiate between these cases. =20 +7.37 KVM_CAP_USERFAULT +---------------------- + +:Architectures: x86, arm64 +:Returns: Informational only, -EINVAL on direct KVM_ENABLE_CAP. + +The presence of this capability indicates that KVM_SET_USER_MEMORY_REGION2= will +accept KVM_MEM_USERFAULT as a valid memslot flag. + +See KVM_SET_USER_MEMORY_REGION2 for more details. + 8. Other capabilities. =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 --=20 2.47.0.338.g60cca15819-goog