Document KVM_SET_USER_MEMORY_REGION and KVM_SET_TSS_ADDR
Subsystems (2)
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(-)
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
@@ -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
Re: [PATCH 1/2] KVM: Document KVM_SET_USER_MEMORY_REGION
Avi Kivity kirjoitti:
Quoted 1 line
Signed-off-by Avi Kivity <[email protected]>
Quoted 58 lines
--- Documentation/kvm/api.txt | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 43 insertions(+), 0 deletions(-)Documentation/kvm/api.txt +43
-0@@ -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
In reply to Avi KivityAm 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_REGIONioctl.
Why? What's wrong with SET_MEM_REGION?
Alex
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_REGIONioctl.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
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_REGIONioctl.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
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_REGIONioctl.
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
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
@@ -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
Re: [PATCH 2/2] KVM: Document KVM_SET_TSS_ADDR
Hi Avi,
Avi Kivity kirjoitti:
Quoted 18 lines
Signed-off-by Avi Kivity <[email protected]>--- Documentation/kvm/api.txt | 16 ++++++++++++++++ 1 files changed, 16 insertions(+), 0 deletions(-)Documentation/kvm/api.txt +5
-0@@ -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
-05. 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
Quoted 12 lines · Pekka Enberg
Quoted 12 lines
+4.35
KVM_SET_TSS_ADDRDocumentation/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 inthe 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
_usedfor_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
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_ADDRDocumentation/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 inthe guest
+physical address space. The region must be within the first 4GB of theQuoted 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 thismemory
Documentation/kvm/api.txt +3
-0+region. + +This ioctl is required on Intel-based hosts.I don't quite understand what it's
_usedfor_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
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