aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/virtual/kvm
diff options
context:
space:
mode:
authorPaul Mackerras <paulus@samba.org>2012-11-19 17:57:20 -0500
committerAlexander Graf <agraf@suse.de>2012-12-05 19:33:57 -0500
commita2932923ccf63c419c77aaa18ac09be98f2c94d8 (patch)
tree391d9fc64d93bac26b442d7f2211dc99dbd10e67 /Documentation/virtual/kvm
parent6b445ad4f839b06e68dd8e178e1168482ca20310 (diff)
KVM: PPC: Book3S HV: Provide a method for userspace to read and write the HPT
A new ioctl, KVM_PPC_GET_HTAB_FD, returns a file descriptor. Reads on this fd return the contents of the HPT (hashed page table), writes create and/or remove entries in the HPT. There is a new capability, KVM_CAP_PPC_HTAB_FD, to indicate the presence of the ioctl. The ioctl takes an argument structure with the index of the first HPT entry to read out and a set of flags. The flags indicate whether the user is intending to read or write the HPT, and whether to return all entries or only the "bolted" entries (those with the bolted bit, 0x10, set in the first doubleword). This is intended for use in implementing qemu's savevm/loadvm and for live migration. Therefore, on reads, the first pass returns information about all HPTEs (or all bolted HPTEs). When the first pass reaches the end of the HPT, it returns from the read. Subsequent reads only return information about HPTEs that have changed since they were last read. A read that finds no changed HPTEs in the HPT following where the last read finished will return 0 bytes. The format of the data provides a simple run-length compression of the invalid entries. Each block of data starts with a header that indicates the index (position in the HPT, which is just an array), the number of valid entries starting at that index (may be zero), and the number of invalid entries following those valid entries. The valid entries, 16 bytes each, follow the header. The invalid entries are not explicitly represented. Signed-off-by: Paul Mackerras <paulus@samba.org> [agraf: fix documentation] Signed-off-by: Alexander Graf <agraf@suse.de>
Diffstat (limited to 'Documentation/virtual/kvm')
-rw-r--r--Documentation/virtual/kvm/api.txt54
1 files changed, 54 insertions, 0 deletions
diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
index 6671fdc0afb1..a5607c571cb3 100644
--- a/Documentation/virtual/kvm/api.txt
+++ b/Documentation/virtual/kvm/api.txt
@@ -2071,6 +2071,60 @@ KVM_S390_INT_EXTERNAL_CALL (vcpu) - sigp external call; source cpu in parm
2071 2071
2072Note that the vcpu ioctl is asynchronous to vcpu execution. 2072Note that the vcpu ioctl is asynchronous to vcpu execution.
2073 2073
20744.78 KVM_PPC_GET_HTAB_FD
2075
2076Capability: KVM_CAP_PPC_HTAB_FD
2077Architectures: powerpc
2078Type: vm ioctl
2079Parameters: Pointer to struct kvm_get_htab_fd (in)
2080Returns: file descriptor number (>= 0) on success, -1 on error
2081
2082This returns a file descriptor that can be used either to read out the
2083entries in the guest's hashed page table (HPT), or to write entries to
2084initialize the HPT. The returned fd can only be written to if the
2085KVM_GET_HTAB_WRITE bit is set in the flags field of the argument, and
2086can only be read if that bit is clear. The argument struct looks like
2087this:
2088
2089/* For KVM_PPC_GET_HTAB_FD */
2090struct kvm_get_htab_fd {
2091 __u64 flags;
2092 __u64 start_index;
2093 __u64 reserved[2];
2094};
2095
2096/* Values for kvm_get_htab_fd.flags */
2097#define KVM_GET_HTAB_BOLTED_ONLY ((__u64)0x1)
2098#define KVM_GET_HTAB_WRITE ((__u64)0x2)
2099
2100The `start_index' field gives the index in the HPT of the entry at
2101which to start reading. It is ignored when writing.
2102
2103Reads on the fd will initially supply information about all
2104"interesting" HPT entries. Interesting entries are those with the
2105bolted bit set, if the KVM_GET_HTAB_BOLTED_ONLY bit is set, otherwise
2106all entries. When the end of the HPT is reached, the read() will
2107return. If read() is called again on the fd, it will start again from
2108the beginning of the HPT, but will only return HPT entries that have
2109changed since they were last read.
2110
2111Data read or written is structured as a header (8 bytes) followed by a
2112series of valid HPT entries (16 bytes) each. The header indicates how
2113many valid HPT entries there are and how many invalid entries follow
2114the valid entries. The invalid entries are not represented explicitly
2115in the stream. The header format is:
2116
2117struct kvm_get_htab_header {
2118 __u32 index;
2119 __u16 n_valid;
2120 __u16 n_invalid;
2121};
2122
2123Writes to the fd create HPT entries starting at the index given in the
2124header; first `n_valid' valid entries with contents from the data
2125written, then `n_invalid' invalid entries, invalidating any previously
2126valid entries found.
2127
2074 2128
20755. The kvm_run structure 21295. The kvm_run structure
2076------------------------ 2130------------------------