[PATCH 0/2] Document KVM_SET_USER_MEMORY_REGION and KVM_SET_TSS_ADDR

[PATCH 0/2] Document KVM_SET_USER_MEMORY_REGION and KVM_SET_TSS_ADDR

[Avi Kivity]

Avi Kivity (2):
  KVM: Document KVM_SET_USER_MEMORY_REGION
  KVM: Document KVM_SET_TSS_ADDR

 Documentation/kvm/api.txt |   59 +++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 59 insertions(+), 0 deletions(-)

[PATCH 1/2] KVM: Document KVM_SET_USER_MEMORY_REGION

[Avi Kivity]

Signed-off-by: Avi Kivity <avi@redhat.com>
---
 Documentation/kvm/api.txt |   43 +++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 43 insertions(+), 0 deletions(-)

diff --git a/Documentation/kvm/api.txt b/Documentation/kvm/api.txt
index d170cb4..22af28a 100644
--- a/Documentation/kvm/api.txt
+++ b/Documentation/kvm/api.txt
@@ -749,6 +749,49 @@ Writes debug registers into the vcpu.
 See KVM_GET_DEBUGREGS for the data structure. The flags field is unused
 yet and must be cleared on entry.
 
+4.34 KVM_SET_USER_MEMORY_REGION
+
+Capability: KVM_CAP_USER_MEM
+Architectures: all
+Type: vm ioctl
+Parameters: struct kvm_userspace_memory_region (in)
+Returns: 0 on success, -1 on error
+
+struct kvm_userspace_memory_region {
+	__u32 slot;
+	__u32 flags;
+	__u64 guest_phys_addr;
+	__u64 memory_size; /* bytes */
+	__u64 userspace_addr; /* start of the userspace allocated memory */
+};
+
+/* for kvm_memory_region::flags */
+#define KVM_MEM_LOG_DIRTY_PAGES  1UL
+
+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.
+
+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
+anonymous memory, ordinary files, and hugetlbfs.
+
+It is recommended that the lower 21 bits of guest_phys_addr and userspace_addr
+be identical.  This allows large pages in the guest to be backed by large
+pages in the host.
+
+The flags field supports just one flag, KVM_MEM_LOG_DIRTY_PAGES, which
+instructs kvm to keep track of writes to memory within the slot.  See
+the KVM_GET_DIRTY_LOG ioctl.
+
+When the KVM_CAP_SYNC_MMU capability, changes in the backing of the memory
+region are automatically reflected into the guest.  For example, an mmap()
+that affects the region will be made visible immediately.  Another example
+is madvise(MADV_DROP).
+
+It is recommended to use this API instead of the KVM_SET_MEMORY_REGION ioctl.
 
 5. The kvm_run structure
 
-- 
1.7.0.2

Re: [PATCH 1/2] KVM: Document KVM_SET_USER_MEMORY_REGION

[Pekka Enberg]

Avi Kivity kirjoitti:
> Signed-off-by: Avi Kivity <avi@redhat.com>

Acked-by: Pekka Enberg <penberg@cs.helsinki.fi>

> ---
>  Documentation/kvm/api.txt |   43 +++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 43 insertions(+), 0 deletions(-)
> 
> diff --git a/Documentation/kvm/api.txt b/Documentation/kvm/api.txt
> index d170cb4..22af28a 100644
> --- a/Documentation/kvm/api.txt
> +++ b/Documentation/kvm/api.txt
> @@ -749,6 +749,49 @@ Writes debug registers into the vcpu.
>  See KVM_GET_DEBUGREGS for the data structure. The flags field is unused
>  yet and must be cleared on entry.
>  
> +4.34 KVM_SET_USER_MEMORY_REGION
> +
> +Capability: KVM_CAP_USER_MEM
> +Architectures: all
> +Type: vm ioctl
> +Parameters: struct kvm_userspace_memory_region (in)
> +Returns: 0 on success, -1 on error
> +
> +struct kvm_userspace_memory_region {
> +	__u32 slot;
> +	__u32 flags;
> +	__u64 guest_phys_addr;
> +	__u64 memory_size; /* bytes */
> +	__u64 userspace_addr; /* start of the userspace allocated memory */
> +};
> +
> +/* for kvm_memory_region::flags */
> +#define KVM_MEM_LOG_DIRTY_PAGES  1UL
> +
> +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.
> +
> +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
> +anonymous memory, ordinary files, and hugetlbfs.
> +
> +It is recommended that the lower 21 bits of guest_phys_addr and userspace_addr
> +be identical.  This allows large pages in the guest to be backed by large
> +pages in the host.
> +
> +The flags field supports just one flag, KVM_MEM_LOG_DIRTY_PAGES, which
> +instructs kvm to keep track of writes to memory within the slot.  See
> +the KVM_GET_DIRTY_LOG ioctl.
> +
> +When the KVM_CAP_SYNC_MMU capability, changes in the backing of the memory
> +region are automatically reflected into the guest.  For example, an mmap()
> +that affects the region will be made visible immediately.  Another example
> +is madvise(MADV_DROP).
> +
> +It is recommended to use this API instead of the KVM_SET_MEMORY_REGION ioctl.
>  
>  5. The kvm_run structure
>  

Re: [PATCH 1/2] KVM: Document KVM_SET_USER_MEMORY_REGION

[Alexander Graf]

Am 25.03.2010 um 11:31 schrieb Avi Kivity <avi@redhat.com>:

>
> +It is recommended to use this API instead of the  
> KVM_SET_MEMORY_REGION ioctl.

Why? What's wrong with SET_MEM_REGION?

Alex

Re: [PATCH 1/2] KVM: Document KVM_SET_USER_MEMORY_REGION

[Avi Kivity]

On 03/25/2010 01:10 PM, Alexander Graf wrote:
>
> Am 25.03.2010 um 11:31 schrieb Avi Kivity <avi@redhat.com>:
>
>>
>> +It is recommended to use this API instead of the 
>> KVM_SET_MEMORY_REGION ioctl.
>
> Why? What's wrong with SET_MEM_REGION?
>

It doesn't allow any control over the memory.  So it found its way into 
Documentation/feature-removal-schedule.txt.

-- 
error compiling committee.c: too many arguments to function

Re: [PATCH 1/2] KVM: Document KVM_SET_USER_MEMORY_REGION

[Alexander Graf]

Am 25.03.2010 um 12:49 schrieb Avi Kivity <avi@redhat.com>:

> On 03/25/2010 01:10 PM, Alexander Graf wrote:
>>
>> Am 25.03.2010 um 11:31 schrieb Avi Kivity <avi@redhat.com>:
>>
>>>
>>> +It is recommended to use this API instead of the  
>>> KVM_SET_MEMORY_REGION ioctl.
>>
>> Why? What's wrong with SET_MEM_REGION?
>>
>
> It doesn't allow any control over the memory.  So it found its way  
> into Documentation/feature-removal-schedule.txt.

Definitely worth adding to the above phrase then.


Alex

Re: [PATCH 1/2] KVM: Document KVM_SET_USER_MEMORY_REGION

[Avi Kivity]

On 03/25/2010 01:54 PM, Alexander Graf wrote:
>
> Am 25.03.2010 um 12:49 schrieb Avi Kivity <avi@redhat.com>:
>
>> On 03/25/2010 01:10 PM, Alexander Graf wrote:
>>>
>>> Am 25.03.2010 um 11:31 schrieb Avi Kivity <avi@redhat.com>:
>>>
>>>>
>>>> +It is recommended to use this API instead of the 
>>>> KVM_SET_MEMORY_REGION ioctl.
>>>
>>> Why? What's wrong with SET_MEM_REGION?
>>>
>>
>> It doesn't allow any control over the memory.  So it found its way 
>> into Documentation/feature-removal-schedule.txt.
>
> Definitely worth adding to the above phrase then.
>

Will do.

-- 
error compiling committee.c: too many arguments to function

[PATCH 2/2] KVM: Document KVM_SET_TSS_ADDR

[Avi Kivity]

Signed-off-by: Avi Kivity <avi@redhat.com>
---
 Documentation/kvm/api.txt |   16 ++++++++++++++++
 1 files changed, 16 insertions(+), 0 deletions(-)

diff --git a/Documentation/kvm/api.txt b/Documentation/kvm/api.txt
index 22af28a..8f45099 100644
--- a/Documentation/kvm/api.txt
+++ b/Documentation/kvm/api.txt
@@ -793,6 +793,22 @@ is madvise(MADV_DROP).
 
 It is recommended to use this API instead of the KVM_SET_MEMORY_REGION ioctl.
 
+4.35 KVM_SET_TSS_ADDR
+
+Capability: KVM_CAP_SET_TSS_ADDR
+Architectures: x86
+Type: vm ioctl
+Parameters: unsigned long tss_address (in)
+Returns: 0 on success, -1 on error
+
+This ioctl defines the physical address of a three-page region in the guest
+physical address space.  The region must be within the first 4GB of the
+guest physical address space and must not conflict with any memory slot
+or any mmio address.  The guest may malfunction if it accesses this memory
+region.
+
+This ioctl is required on Intel-based hosts.
+
 5. The kvm_run structure
 
 Application code obtains a pointer to the kvm_run structure by
-- 
1.7.0.2

Re: [PATCH 2/2] KVM: Document KVM_SET_TSS_ADDR

[Pekka Enberg]

Hi Avi,

Avi Kivity kirjoitti:
> Signed-off-by: Avi Kivity <avi@redhat.com>
> ---
>  Documentation/kvm/api.txt |   16 ++++++++++++++++
>  1 files changed, 16 insertions(+), 0 deletions(-)
> 
> diff --git a/Documentation/kvm/api.txt b/Documentation/kvm/api.txt
> index 22af28a..8f45099 100644
> --- a/Documentation/kvm/api.txt
> +++ b/Documentation/kvm/api.txt
> @@ -793,6 +793,22 @@ is madvise(MADV_DROP).
>  
>  It is recommended to use this API instead of the KVM_SET_MEMORY_REGION ioctl.
>  
> +4.35 KVM_SET_TSS_ADDR
> +
> +Capability: KVM_CAP_SET_TSS_ADDR
> +Architectures: x86
> +Type: vm ioctl
> +Parameters: unsigned long tss_address (in)
> +Returns: 0 on success, -1 on error
> +
> +This ioctl defines the physical address of a three-page region in the guest
> +physical address space.  The region must be within the first 4GB of the
> +guest physical address space and must not conflict with any memory slot
> +or any mmio address.  The guest may malfunction if it accesses this memory
> +region.
> +
> +This ioctl is required on Intel-based hosts.

I don't quite understand what it's _used for_ from the above 
description. I assume it's about task state segment...?

>  5. The kvm_run structure
>  
>  Application code obtains a pointer to the kvm_run structure by

Re: [PATCH 2/2] KVM: Document KVM_SET_TSS_ADDR

[Avi Kivity]

On 03/25/2010 12:36 PM, Pekka Enberg wrote:
>> +4.35 KVM_SET_TSS_ADDR
>> +
>> +Capability: KVM_CAP_SET_TSS_ADDR
>> +Architectures: x86
>> +Type: vm ioctl
>> +Parameters: unsigned long tss_address (in)
>> +Returns: 0 on success, -1 on error
>> +
>> +This ioctl defines the physical address of a three-page region in 
>> the guest
>> +physical address space.  The region must be within the first 4GB of the
>> +guest physical address space and must not conflict with any memory slot
>> +or any mmio address.  The guest may malfunction if it accesses this 
>> memory
>> +region.
>> +
>> +This ioctl is required on Intel-based hosts.
>
>
> I don't quite understand what it's _used for_ from the above 
> description. I assume it's about task state segment...?

It's a quirk in the Intel implementation of hardware virtualization 
extensions.  You cannot enter guest mode in vmx with the guest cr0.pe 
cleared (i.e. real mode), so kvm enters the guest in vm86 mode which is 
fairly similar and tries to massage things so it looks to the guest as 
if it is running in real mode.  Unfortunately, vm86 mode requires a task 
state segment in the address space, and there is no way for us to hide 
it.  kvm doesn't know anything about the guest physical memory map, so 
it has to rely on userspace to supply an unused region.

I don't think such a technical description of an implementation detail 
has a place in the API reference; maybe in internal documentation.

-- 
error compiling committee.c: too many arguments to function

Re: [PATCH 2/2] KVM: Document KVM_SET_TSS_ADDR

[Pekka Enberg]

Avi Kivity kirjoitti:
> On 03/25/2010 12:36 PM, Pekka Enberg wrote:
>>> +4.35 KVM_SET_TSS_ADDR
>>> +
>>> +Capability: KVM_CAP_SET_TSS_ADDR
>>> +Architectures: x86
>>> +Type: vm ioctl
>>> +Parameters: unsigned long tss_address (in)
>>> +Returns: 0 on success, -1 on error
>>> +
>>> +This ioctl defines the physical address of a three-page region in 
>>> the guest
>>> +physical address space.  The region must be within the first 4GB of the
>>> +guest physical address space and must not conflict with any memory slot
>>> +or any mmio address.  The guest may malfunction if it accesses this 
>>> memory
>>> +region.
>>> +
>>> +This ioctl is required on Intel-based hosts.
>>
>> I don't quite understand what it's _used for_ from the above 
>> description. I assume it's about task state segment...?
> 
> It's a quirk in the Intel implementation of hardware virtualization 
> extensions.  You cannot enter guest mode in vmx with the guest cr0.pe 
> cleared (i.e. real mode), so kvm enters the guest in vm86 mode which is 
> fairly similar and tries to massage things so it looks to the guest as 
> if it is running in real mode.  Unfortunately, vm86 mode requires a task 
> state segment in the address space, and there is no way for us to hide 
> it.  kvm doesn't know anything about the guest physical memory map, so 
> it has to rely on userspace to supply an unused region.
> 
> I don't think such a technical description of an implementation detail 
> has a place in the API reference; maybe in internal documentation.

Sure but it would be nice to have something along the lines of "This is 
needed on Intel hardware because of a quirk in the virtualization 
implementation" and maybe point the reader to a more appropriate 
document (internals document, Intel manuals, ...).

			Pekka

Re: [PATCH 2/2] KVM: Document KVM_SET_TSS_ADDR

[Avi Kivity]

On 03/25/2010 02:00 PM, Pekka Enberg wrote:
>> I don't think such a technical description of an implementation 
>> detail has a place in the API reference; maybe in internal 
>> documentation.
>
>
> Sure but it would be nice to have something along the lines of "This 
> is needed on Intel hardware because of a quirk in the virtualization 
> implementation" and maybe point the reader to a more appropriate 
> document (internals document, Intel manuals, ...).

Ok, will add.

-- 
error compiling committee.c: too many arguments to function