Ackerley Tng <[email protected]> writes: Here's iteration 2 of the attributes, after getting a much clearer idea of the use cases across platforms at the last guest_memfd biweekly.
Please comment in this context! I'm planning for this text to make it to Documentation/virt/kvm/api.rst. > Ackerley Tng <[email protected]> writes: > >> >> [...snip...] >> >> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst >> index 23ec0b0c3e22..26e80745c8b4 100644 >> --- a/Documentation/virt/kvm/api.rst >> +++ b/Documentation/virt/kvm/api.rst >> @@ -117,7 +117,7 @@ description: >> x86 includes both i386 and x86_64. >> >> Type: >> - system, vm, or vcpu. >> + system, vm, vcpu or guest_memfd. >> >> Parameters: >> what parameters are accepted by the ioctl. >> @@ -6523,11 +6523,22 @@ the capability to be present. >> --------------------------------- >> >> :Capability: KVM_CAP_MEMORY_ATTRIBUTES2 >> -:Architectures: x86 >> -:Type: vm ioctl >> +:Architectures: all >> +:Type: vm, guest_memfd ioctl >> :Parameters: struct kvm_memory_attributes2 (in/out) >> :Returns: 0 on success, <0 on error >> >> +Errors: >> + >> + ========== =============================================================== >> + EINVAL The specified `offset` or `size` were invalid (e.g. not >> + page aligned, causes an overflow, or size is zero). >> + EFAULT The parameter address was invalid. >> + EAGAIN Some page within requested range had unexpected refcounts. The >> + offset of the page will be returned in `error_offset`. >> + ENOMEM Ran out of memory trying to track private/shared state EOPNOTSUPP The specified content policy is not supported while setting the requested attribute >> + ========== =============================================================== >> + >> KVM_SET_MEMORY_ATTRIBUTES2 is an extension to >> KVM_SET_MEMORY_ATTRIBUTES that supports returning (writing) values to >> userspace. The original (pre-extension) fields are shared with >> @@ -6538,15 +6549,42 @@ Attribute values are shared with >> KVM_SET_MEMORY_ATTRIBUTES. >> :: >> >> struct kvm_memory_attributes2 { >> - __u64 address; >> + /* in */ >> + union { >> + __u64 address; >> + __u64 offset; >> + }; >> __u64 size; >> __u64 attributes; >> __u64 flags; >> - __u64 reserved[12]; >> + /* out */ >> + __u64 error_offset; >> + __u64 reserved[11]; >> }; >> >> #define KVM_MEMORY_ATTRIBUTE_PRIVATE (1ULL << 3) >> >> +Set attributes for a range of offsets within a guest_memfd to >> +KVM_MEMORY_ATTRIBUTE_PRIVATE to limit the specified guest_memfd backed >> +memory range for guest_use. Even if KVM_CAP_GUEST_MEMFD_MMAP is >> +supported, after a successful call to set >> +KVM_MEMORY_ATTRIBUTE_PRIVATE, the requested range will not be mappable >> +into host userspace and will only be mappable by the guest. >> + >> +To allow the range to be mappable into host userspace again, call >> +KVM_SET_MEMORY_ATTRIBUTES2 on the guest_memfd again with >> +KVM_MEMORY_ATTRIBUTE_PRIVATE unset. >> + >> +If this ioctl returns -EAGAIN, the offset of the page with unexpected >> +refcounts will be returned in `error_offset`. This can occur if there >> +are transient refcounts on the pages, taken by other parts of the >> +kernel. >> + >> +Userspace is expected to figure out how to remove all known refcounts >> +on the shared pages, such as refcounts taken by get_user_pages(), and >> +try the ioctl again. A possible source of these long term refcounts is >> +if the guest_memfd memory was pinned in IOMMU page tables. >> + Memory *content* policies can be requested while setting memory attributes. This defines: - What the host reads after a private to shared conversion - What the guest reads after a shared to private conversion (if applicable) The policy definitions below provide more details: ``KVM_SET_MEMORY_ATTRIBUTES2_CONTENT_POLICY_ZERO`` (default) On a private to shared conversion, the host will read zeros from the converted memory on the next fault after successful return of the KVM_SET_MEMORY_ATTRIBUTES2 ioctl. This is not supported (-EOPNOTSUPP) for a shared to private conversion. While some CoCo implementations do zero memory contents such that the guest reads zeros after conversion, the guest is not expected to trust host-provided zeroing, hence as a UAPI policy, KVM does not make any such guarantees. For testing purposes, the KVM_X86_SW_PROTECTED_VM testing vehicle will support this policy and ensure zeroing for conversions in both directions. ``KVM_SET_MEMORY_ATTRIBUTES2_CONTENT_POLICY_PRESERVE`` On private/shared conversions in both directions, memory contents will be preserved and readable. As a concrete example, if the host writes ``0xbeef`` to memory and converts the memory to shared, the guest will also read ``0xbeef``, after any necessary hardware or software provided decryption. After a reverse shared to private conversion, the host will also read ``0xbeef``. pKVM (ARM) is the first user of this policy. Since pKVM does not protect memory with encryption, a content policy to preserve memory will not will not involve any decryption. The guest will be able to read what the host wrote with full content preservation. For testing purposes, the KVM_X86_SW_PROTECTED_VM testing vehicle will support this policy and the contents of converted memory will be preserved. ``KVM_SET_MEMORY_ATTRIBUTES2_CONTENT_POLICY_NONE`` This is an explicit request that KVM provide no guarantees on memory contents after conversion. Neither host nor guest should expect any guarantees about the memory contents after conversion. For testing purposes, the KVM_X86_SW_PROTECTED_VM testing vehicle will support this policy and every byte of converted memory will read ``0xab``. >> See also: :ref: `KVM_SET_MEMORY_ATTRIBUTES`. >> > > [...snip...] >
