[PATCH] Documentation: kvm: clarify KVM_SET_USER_MEMORY_REGION

[PATCH] Documentation: kvm: clarify KVM_SET_USER_MEMORY_REGION

[Paolo Bonzini]

The documentation does not mention how to delete a slot, add the
information.

Reported-by: Nathaniel McCallum <npmccallum@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
 Documentation/virtual/kvm/api.txt | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
index f39969d0121e..67068c47c591 100644
--- a/Documentation/virtual/kvm/api.txt
+++ b/Documentation/virtual/kvm/api.txt
@@ -1114,14 +1114,12 @@ struct kvm_userspace_memory_region {
 #define KVM_MEM_LOG_DIRTY_PAGES	(1UL << 0)
 #define KVM_MEM_READONLY	(1UL << 1)
 
-This ioctl allows the user to create or modify a guest physical memory
-slot.  When changing an existing slot, it may be moved in the guest
-physical memory space, or its flags may be modified.  It may not be
-resized.  Slots may not overlap in guest physical address space.
-Bits 0-15 of "slot" specifies the slot id and this value should be
-less than the maximum number of user memory slots supported per VM.
-The maximum allowed slots can be queried using KVM_CAP_NR_MEMSLOTS,
-if this capability is supported by the architecture.
+This ioctl allows the user to create, modify or delete a guest physical
+memory slot.  Bits 0-15 of "slot" specify the slot id and this value
+should be less than the maximum number of user memory slots supported per
+VM.  The maximum allowed slots can be queried using KVM_CAP_NR_MEMSLOTS,
+if this capability is supported by the architecture.  Slots may not
+overlap in guest physical address space.
 
 If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 of "slot"
 specifies the address space which is being modified.  They must be
@@ -1130,6 +1128,10 @@ KVM_CAP_MULTI_ADDRESS_SPACE capability.  Slots in separate address spaces
 are unrelated; the restriction on overlapping slots only applies within
 each address space.
 
+Deleting a slot is done by passing zero for memory_size.  When changing
+an existing slot, it may be moved in the guest physical memory space,
+or its flags may be modified, but it may not be resized.
+
 Memory for the region is taken starting at the address denoted by the
 field userspace_addr, which must point at user addressable memory for
 the entire memory slot size.  Any object may back this memory, including
-- 
1.8.3.1

Re: [PATCH] Documentation: kvm: clarify KVM_SET_USER_MEMORY_REGION

[David Hildenbrand]

On 28.03.19 17:31, Paolo Bonzini wrote:
> The documentation does not mention how to delete a slot, add the
> information.
> 
> Reported-by: Nathaniel McCallum <npmccallum@redhat.com>
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> ---
>  Documentation/virtual/kvm/api.txt | 18 ++++++++++--------
>  1 file changed, 10 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
> index f39969d0121e..67068c47c591 100644
> --- a/Documentation/virtual/kvm/api.txt
> +++ b/Documentation/virtual/kvm/api.txt
> @@ -1114,14 +1114,12 @@ struct kvm_userspace_memory_region {
>  #define KVM_MEM_LOG_DIRTY_PAGES	(1UL << 0)
>  #define KVM_MEM_READONLY	(1UL << 1)
>  
> -This ioctl allows the user to create or modify a guest physical memory
> -slot.  When changing an existing slot, it may be moved in the guest
> -physical memory space, or its flags may be modified.  It may not be
> -resized.  Slots may not overlap in guest physical address space.
> -Bits 0-15 of "slot" specifies the slot id and this value should be
> -less than the maximum number of user memory slots supported per VM.
> -The maximum allowed slots can be queried using KVM_CAP_NR_MEMSLOTS,
> -if this capability is supported by the architecture.
> +This ioctl allows the user to create, modify or delete a guest physical
> +memory slot.  Bits 0-15 of "slot" specify the slot id and this value
> +should be less than the maximum number of user memory slots supported per
> +VM.  The maximum allowed slots can be queried using KVM_CAP_NR_MEMSLOTS,
> +if this capability is supported by the architecture.  Slots may not
> +overlap in guest physical address space.
>  
>  If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 of "slot"
>  specifies the address space which is being modified.  They must be
> @@ -1130,6 +1128,10 @@ KVM_CAP_MULTI_ADDRESS_SPACE capability.  Slots in separate address spaces
>  are unrelated; the restriction on overlapping slots only applies within
>  each address space.
>  
> +Deleting a slot is done by passing zero for memory_size.  When changing
> +an existing slot, it may be moved in the guest physical memory space,
> +or its flags may be modified, but it may not be resized.
> +

BTW, still looking for a way to resize atomically without having to
remove/add :)

Reviewed-by: David Hildenbrand <david@redhat.com>


-- 

Thanks,

David / dhildenb