Only in trunk: doc diff -urp trunk-unchanged/kernel/include/linux/kvm.h trunk/kernel/include/linux/kvm.h --- trunk-unchanged/kernel/include/linux/kvm.h 2006-12-19 14:44:26.000000000 +0100 +++ trunk/kernel/include/linux/kvm.h 2006-12-19 14:44:31.000000000 +0100 @@ -96,16 +96,26 @@ struct kvm_run { }; /* for KVM_GET_REGS and KVM_SET_REGS */ +/*! + * This structure contains the general registers (non segment, non descriptors) + * of a VCPU after KVM_GET_REGS, and is used to set the VCPUs registers in a KVM_SET_REGS. + * + * This structure is also used with the user-space functions kvm_set_regs() and kvm_get_regs() + */ struct kvm_regs { /* in */ __u32 vcpu; __u32 padding; /* out (KVM_GET_REGS) / in (KVM_SET_REGS) */ + /// General purpose registers __u64 rax, rbx, rcx, rdx; + /// General purpose indexes __u64 rsi, rdi, rsp, rbp; - __u64 r8, r9, r10, r11; - __u64 r12, r13, r14, r15; + /// 64bit extension registers + __u64 r8, r9, r10, r11, r12, r13, r14, r15; + + /// Instruction-pointer and EFLAGS __u64 rip, rflags; }; diff -urp trunk-unchanged/user/kvmctl.c trunk/user/kvmctl.c --- trunk-unchanged/user/kvmctl.c 2006-12-19 14:44:26.000000000 +0100 +++ trunk/user/kvmctl.c 2006-12-19 14:44:31.000000000 +0100 @@ -14,6 +14,7 @@ * This work is licensed under the GNU LGPL license, version 2. */ + #include #include #include @@ -25,10 +26,18 @@ #define PAGE_SIZE 4096ul +/** + * \brief The KVM context + * + * The verbose KVM context + */ struct kvm_context { + /// Filedescriptor to /dev/kvm int fd; + /// Callbacks that KVM uses to emulate various unvirtualizable functionality struct kvm_callbacks *callbacks; void *opaque; + /// A pointer to the memory used as the physical memory for the guest void *physical_memory; }; @@ -69,6 +78,7 @@ static int translate(kvm_context_t kvm, return 0; } + kvm_context_t kvm_init(struct kvm_callbacks *callbacks, void *opaque) { diff -urp trunk-unchanged/user/kvmctl.h trunk/user/kvmctl.h --- trunk-unchanged/user/kvmctl.h 2006-12-19 14:44:26.000000000 +0100 +++ trunk/user/kvmctl.h 2006-12-19 14:44:31.000000000 +0100 @@ -1,6 +1,11 @@ +/** \file kvmctl.h + * libkvm API + */ + #ifndef KVMCTL_H #define KVMCTL_H + #define __user /* temporary, until installed via make headers_install */ #include #include @@ -9,48 +14,208 @@ struct kvm_context; typedef struct kvm_context *kvm_context_t; +/*! + * \brief KVM callbacks structure + * + * This structure holds pointers to various functions that KVM will call + * when it encounters something that cannot be virtualized, such as + * accessing hardware devices via MMIO or regular IO. + */ struct kvm_callbacks { int (*cpuid)(void *opaque, uint64_t *rax, uint64_t *rbx, uint64_t *rcx, uint64_t *rdx); + /// For 8bit IO reads from the guest (Usually when executing 'inb') int (*inb)(void *opaque, uint16_t addr, uint8_t *data); + /// For 16bit IO reads from the guest (Usually when executing 'inw') int (*inw)(void *opaque, uint16_t addr, uint16_t *data); + /// For 32bit IO reads from the guest (Usually when executing 'inl') int (*inl)(void *opaque, uint16_t addr, uint32_t *data); + /// For 8bit IO writes from the guest (Usually when executing 'outb') int (*outb)(void *opaque, uint16_t addr, uint8_t data); + /// For 16bit IO writes from the guest (Usually when executing 'outw') int (*outw)(void *opaque, uint16_t addr, uint16_t data); + /// For 32bit IO writes from the guest (Usually when executing 'outl') int (*outl)(void *opaque, uint16_t addr, uint32_t data); + /// For 8bit memory reads from unmapped memory (For MMIO devices) int (*readb)(void *opaque, uint64_t addr, uint8_t *data); + /// For 16bit memory reads from unmapped memory (For MMIO devices) int (*readw)(void *opaque, uint64_t addr, uint16_t *data); + /// For 32bit memory reads from unmapped memory (For MMIO devices) int (*readl)(void *opaque, uint64_t addr, uint32_t *data); + /// For 64bit memory reads from unmapped memory (For MMIO devices) int (*readq)(void *opaque, uint64_t addr, uint64_t *data); + /// For 8bit memory writes to unmapped memory (For MMIO devices) int (*writeb)(void *opaque, uint64_t addr, uint8_t data); + /// For 16bit memory writes to unmapped memory (For MMIO devices) int (*writew)(void *opaque, uint64_t addr, uint16_t data); + /// For 32bit memory writes to unmapped memory (For MMIO devices) int (*writel)(void *opaque, uint64_t addr, uint32_t data); + /// For 64bit memory writes to unmapped memory (For MMIO devices) int (*writeq)(void *opaque, uint64_t addr, uint64_t data); int (*debug)(void *opaque, int vcpu); int (*halt)(void *opaque, int vcpu); int (*io_window)(void *opaque); }; -/* Create a new kvm context */ +/*! + * \brief Create new KVM context + * + * This creates a new kvm_context. A KVM context is a small area of data that + * holds information about the KVM instance that gets created by this call.\n + * This should always be your first call to KVM. + * + * \param callbacks Pointer to a valid kvm_callbacks structure + * \return NULL on failure + */ kvm_context_t kvm_init(struct kvm_callbacks *callbacks, void *opaque); -/* Cleanup the kvm context */ + +/*! + * \brief Cleanup the KVM context + * + * Should always be called when closing down KVM.\n + * Exception: If kvm_init() fails, this function should not be called, as the context would be invalid + * + * \param kvm Pointer to the kvm_context that is to be freed + */ void kvm_finalize(kvm_context_t kvm); + +/*! + * \brief Create new virtual machine + * + * This creates a new virtual machine, maps physical RAM to it, and creates a virtual CPU + * for it.\n + * \n + * Memory gets mapped for addresses 0->0xA0000, 0xC0000->phys_mem_bytes + * + * \param phys_mem_bytes The amount of physical ram you want the VM to have + * \param phys_mem This pointer will be set to point to the memory that kvm_create allocates for physical RAM + * \return 0 on success + */ int kvm_create(kvm_context_t kvm, unsigned long phys_mem_bytes, void **phys_mem); + +/*! + * \brief Start the VCPU + * + * This starts the VCPU and virtualization is started.\n + * \n + * This function will not return until any of these conditions are met: + * - An IO/MMIO handler does not return "0" + * - An exception that neither the guest OS, nor KVM can handle occurs + * + * \param kvm Pointer to the current kvm_context + * \param vcpu Which virtual CPU should be started + * \return 0 on success, but you really shouldn't expect this function to return except for when an error has occured + */ int kvm_run(kvm_context_t kvm, int vcpu); -int kvm_get_regs(kvm_context_t, int vcpu, struct kvm_regs *regs); -int kvm_set_regs(kvm_context_t, int vcpu, struct kvm_regs *regs); -int kvm_get_sregs(kvm_context_t, int vcpu, struct kvm_sregs *regs); -int kvm_set_sregs(kvm_context_t, int vcpu, struct kvm_sregs *regs); + +/*! + * \brief Read VCPU registers + * + * This gets the GP registers from the VCPU and outputs them + * into a kvm_regs structure + * + * \note This function returns a \b copy of the VCPUs registers.\n + * If you wish to modify the VCPUs GP registers, you should call kvm_set_regs() + * + * \param kvm Pointer to the current kvm_context + * \param vcpu Which virtual CPU should get dumped + * \param regs Pointer to a kvm_regs which will be populated with the VCPUs registers values + * \return 0 on success + */ +int kvm_get_regs(kvm_context_t kvm, int vcpu, struct kvm_regs *regs); + +/*! + * \brief Write VCPU registers + * + * This sets the GP registers on the VCPU from a kvm_regs structure + * + * \note When this function returns, the regs pointer and the data it points to can be discarded + * \param kvm Pointer to the current kvm_context + * \param vcpu Which virtual CPU should get dumped + * \param regs Pointer to a kvm_regs which will be populated with the VCPUs registers values + * \return 0 on success + */ +int kvm_set_regs(kvm_context_t kvm, int vcpu, struct kvm_regs *regs); + +/*! + * \brief Read VCPU system registers + * + * This gets the non-GP registers from the VCPU and outputs them + * into a kvm_sregs structure + * + * \note This function returns a \b copy of the VCPUs registers.\n + * If you wish to modify the VCPUs non-GP registers, you should call kvm_set_sregs() + * + * \param kvm Pointer to the current kvm_context + * \param vcpu Which virtual CPU should get dumped + * \param regs Pointer to a kvm_sregs which will be populated with the VCPUs registers values + * \return 0 on success + */ +int kvm_get_sregs(kvm_context_t kvm, int vcpu, struct kvm_sregs *regs); + +/*! + * \brief Write VCPU system registers + * + * This sets the non-GP registers on the VCPU from a kvm_sregs structure + * + * \note When this function returns, the regs pointer and the data it points to can be discarded + * \param kvm Pointer to the current kvm_context + * \param vcpu Which virtual CPU should get dumped + * \param regs Pointer to a kvm_sregs which will be populated with the VCPUs registers values + * \return 0 on success + */ +int kvm_set_sregs(kvm_context_t kvm, int vcpu, struct kvm_sregs *regs); + struct kvm_msr_list *kvm_get_msr_list(kvm_context_t); int kvm_get_msrs(kvm_context_t, int vcpu, struct kvm_msr_entry *msrs, int n); int kvm_set_msrs(kvm_context_t, int vcpu, struct kvm_msr_entry *msrs, int n); -int kvm_inject_irq(kvm_context_t, int vcpu, unsigned irq); + +/*! + * \brief Set the IRQ pins of the VCPU + * + * This sets the IRQ flags of the VCPU + * + * \param kvm Pointer to the current kvm_context + * \param vcpu Which virtual CPU should get dumped + * \param irq Bitmask for the IRQ pins + * \return 0 on success + */ +int kvm_inject_irq(kvm_context_t kvm, int vcpu, unsigned irq); int kvm_guest_debug(kvm_context_t, int vcpu, struct kvm_debug_guest *dbg); -int kvm_dump_vcpu(kvm_context_t , int vcpu); -void kvm_show_regs(kvm_context_t, int vcpu); + +/*! + * \brief Dump all VCPU information + * + * This dumps \b all the information that KVM has about a virtual CPU, namely: + * - GP Registers + * - System registers (selectors, descriptors, etc) + * - VMCS Data + * - MSRS + * - Pending interrupts + * + * \param kvm Pointer to the current kvm_context + * \param vcpu Which virtual CPU should get dumped + * \return 0 on success + */ +int kvm_dump_vcpu(kvm_context_t kvm, int vcpu); + +/*! + * \brief Dump VCPU registers + * + * This dumps some of the information that KVM has about a virtual CPU, namely: + * - GP Registers + * + * A much more verbose version of this is available as kvm_dump_vcpu() + * + * \param kvm Pointer to the current kvm_context + * \param vcpu Which virtual CPU should get dumped + * \return 0 on success + */ +void kvm_show_regs(kvm_context_t kvm, int vcpu); + void *kvm_create_phys_mem(kvm_context_t, unsigned long phys_start, unsigned long len, int slot, int log, int writable); void kvm_destroy_phys_mem(kvm_context_t, unsigned long phys_start,