Skip to contentSkip to conversation

Document KVM_SET_USER_MEMORY_REGION and KVM_SET_TSS_ADDR

PATCH In review Avi Kivity 3 participants 12 messages Mar 25, 2010

Subsystems (2)
lore
Share & tools
lore

Avi Kivity

author
#0 lore raw

cover Document KVM_SET_USER_MEMORY_REGION and KVM_SET_TSS_ADDR

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(-)
author
#1 lore raw

PATCH 1/2 KVM: Document KVM_SET_USER_MEMORY_REGION

---
 Documentation/kvm/api.txt |   43 +++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 43 insertions(+), 0 deletions(-)
Documentation/kvm/api.txt +43 -0
index d170cb4..22af28a 100644
@@ -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
 
Signature · 1 line
1.7.0.2
Acked-by on v1 1/2
#2 lore raw

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

Avi Kivity kirjoitti:

Quoted 1 line
Quoted 58 lines
---
 Documentation/kvm/api.txt |   43 +++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 43 insertions(+), 0 deletions(-)
Documentation/kvm/api.txt +43 -0
index d170cb4..22af28a 100644
@@ -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
 
#3 lore raw

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

In reply to Avi Kivity

Am 25.03.2010 um 11:31 schrieb Avi Kivity <[email protected]>:

Quoted 3 lines

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

Why? What's wrong with SET_MEM_REGION?

Alex

author
#4 lore raw

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

Quoted 9 lines · Alexander Graf

Am 25.03.2010 um 11:31 schrieb Avi Kivity <[email protected]>:

Quoted 3 lines

+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.

Signature · 1 line
error compiling committee.c: too many arguments to function
#5 lore raw

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

Am 25.03.2010 um 12:49 schrieb Avi Kivity <[email protected]>:

Quoted 5 lines · Alexander Graf
Quoted 4 lines

Am 25.03.2010 um 11:31 schrieb Avi Kivity <[email protected]>:

Quoted 1 line
Quoted 7 lines
Quoted 5 lines
Quoted 2 lines

+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

author
#6 lore raw

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

Quoted 11 lines · Alexander Graf

Am 25.03.2010 um 12:49 schrieb Avi Kivity <[email protected]>:

Quoted 8 lines · Alexander Graf
Quoted 7 lines

Am 25.03.2010 um 11:31 schrieb Avi Kivity <[email protected]>:

Quoted 3 lines

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

Quoted 7 lines
Quoted 4 lines
Quoted 2 lines

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.

Signature · 1 line
error compiling committee.c: too many arguments to function
author
#7 lore raw

PATCH 2/2 KVM: Document KVM_SET_TSS_ADDR

In reply to Avi Kivity
---
 Documentation/kvm/api.txt |   16 ++++++++++++++++
 1 files changed, 16 insertions(+), 0 deletions(-)
Documentation/kvm/api.txt +16 -0
index 22af28a..8f45099 100644
@@ -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
Signature · 1 line
1.7.0.2
#8 lore raw

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

Hi Avi,

Avi Kivity kirjoitti:

Quoted 18 lines
---
 Documentation/kvm/api.txt |   16 ++++++++++++++++
 1 files changed, 16 insertions(+), 0 deletions(-)
Documentation/kvm/api.txt +5 -0
index 22af28a..8f45099 100644
@@ -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

Documentation/kvm/api.txt is madvise(MADV_DROP). · line 810

Quoted 10 lines
Documentation/kvm/api.txt +10 -0
+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...?

Quoted 3 lines
Documentation/kvm/api.txt +0 -0
 5. The kvm_run structure
 
 Application code obtains a pointer to the kvm_run structure by
author
#9 lore raw

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

Quoted 12 lines · Pekka Enberg
Quoted 12 lines

+4.35 KVM_SET_TSS_ADDR

Documentation/kvm/api.txt +8 -0
+
+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

Documentation/kvm/api.txt +2 -0
+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
Quoted 8 lines

Documentation/kvm/api.txt is madvise(MADV_DROP). · line 810

Quoted 5 lines

+or any mmio address. The guest may malfunction if it accesses this memory

Documentation/kvm/api.txt +3 -0
+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.

Signature · 1 line
error compiling committee.c: too many arguments to function
#10 lore raw

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

Avi Kivity kirjoitti:

Quoted 21 lines · Pekka Enberg
Quoted 11 lines
Quoted 11 lines

+4.35 KVM_SET_TSS_ADDR

Documentation/kvm/api.txt +8 -0
+
+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

Quoted 8 lines

Documentation/kvm/api.txt is madvise(MADV_DROP). · line 810

Quoted 6 lines
(quoted diff) +2 -0
+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

Documentation/kvm/api.txt +3 -0
+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...?

Quoted 3 lines

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

author
#11 lore raw

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

Quoted 4 lines · Pekka Enberg
Quoted 1 line

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.

Signature · 1 line
error compiling committee.c: too many arguments to function