user/kvmctl.h

   1 /** \file kvmctl.h
   2  * libkvm API
   3  */
   4
   5 #ifndef KVMCTL_H
   6 #define KVMCTL_H
   7
   8 #define __user /* temporary, until installed via make headers_install */
   9 #include <linux/kvm.h>
  10 #include <stdint.h>
  11
  12 struct kvm_context;
  13
  14 typedef struct kvm_context *kvm_context_t;
  15
  16 /*!
  17  * \brief KVM callbacks structure
  18  *
  19  * This structure holds pointers to various functions that KVM will call
  20  * when it encounters something that cannot be virtualized, such as
  21  * accessing hardware devices via MMIO or regular IO.
  22  */
  23 struct kvm_callbacks {
  24     int (*cpuid)(void *opaque,
  25                   uint64_t *rax, uint64_t *rbx, uint64_t *rcx, uint64_t *rdx);
  26         /// For 8bit IO reads from the guest (Usually when executing 'inb')
  27     int (*inb)(void *opaque, uint16_t addr, uint8_t *data);
  28         /// For 16bit IO reads from the guest (Usually when executing 'inw')
  29     int (*inw)(void *opaque, uint16_t addr, uint16_t *data);
  30         /// For 32bit IO reads from the guest (Usually when executing 'inl')
  31     int (*inl)(void *opaque, uint16_t addr, uint32_t *data);
  32         /// For 8bit IO writes from the guest (Usually when executing 'outb')
  33     int (*outb)(void *opaque, uint16_t addr, uint8_t data);
  34         /// For 16bit IO writes from the guest (Usually when executing 'outw')
  35     int (*outw)(void *opaque, uint16_t addr, uint16_t data);
  36         /// For 32bit IO writes from the guest (Usually when executing 'outl')
  37     int (*outl)(void *opaque, uint16_t addr, uint32_t data);
  38         /// For 8bit memory reads from unmapped memory (For MMIO devices)
  39     int (*readb)(void *opaque, uint64_t addr, uint8_t *data);
  40         /// For 16bit memory reads from unmapped memory (For MMIO devices)
  41     int (*readw)(void *opaque, uint64_t addr, uint16_t *data);
  42         /// For 32bit memory reads from unmapped memory (For MMIO devices)
  43     int (*readl)(void *opaque, uint64_t addr, uint32_t *data);
  44         /// For 64bit memory reads from unmapped memory (For MMIO devices)
  45     int (*readq)(void *opaque, uint64_t addr, uint64_t *data);
  46         /// For 8bit memory writes to unmapped memory (For MMIO devices)
  47     int (*writeb)(void *opaque, uint64_t addr, uint8_t data);
  48         /// For 16bit memory writes to unmapped memory (For MMIO devices)
  49     int (*writew)(void *opaque, uint64_t addr, uint16_t data);
  50         /// For 32bit memory writes to unmapped memory (For MMIO devices)
  51     int (*writel)(void *opaque, uint64_t addr, uint32_t data);
  52         /// For 64bit memory writes to unmapped memory (For MMIO devices)
  53     int (*writeq)(void *opaque, uint64_t addr, uint64_t data);
  54     int (*debug)(void *opaque, int vcpu);
  55         /*!
  56          * \brief Called when the VCPU issues an 'hlt' instruction.
  57          *
  58          * Typically, you should yeild here to prevent 100% CPU utilization
  59          * on the host CPU.
  60          */
  61     int (*halt)(void *opaque, int vcpu);
  62     int (*io_window)(void *opaque);
  63     int (*try_push_interrupts)(void *opaque);
  64     void (*post_kvm_run)(void *opaque, struct kvm_run *kvm_run);
  65     void (*pre_kvm_run)(void *opaque, struct kvm_run *kvm_run);
  66 };
  67
  68 /*!
  69  * \brief Create new KVM context
  70  *
  71  * This creates a new kvm_context. A KVM context is a small area of data that
  72  * holds information about the KVM instance that gets created by this call.\n
  73  * This should always be your first call to KVM.
  74  *
  75  * \param callbacks Pointer to a valid kvm_callbacks structure
  76  * \param opaque Not used
  77  * \return NULL on failure
  78  */
  79 kvm_context_t kvm_init(struct kvm_callbacks *callbacks,
  80                        void *opaque);
  81
  82 /*!
  83  * \brief Cleanup the KVM context
  84  *
  85  * Should always be called when closing down KVM.\n
  86  * Exception: If kvm_init() fails, this function should not be called, as the
  87  * context would be invalid
  88  *
  89  * \param kvm Pointer to the kvm_context that is to be freed
  90  */
  91 void kvm_finalize(kvm_context_t kvm);
  92
  93 /*!
  94  * \brief Create new virtual machine
  95  *
  96  * This creates a new virtual machine, maps physical RAM to it, and creates a
  97  * virtual CPU for it.\n
  98  * \n
  99  * Memory gets mapped for addresses 0->0xA0000, 0xC0000->phys_mem_bytes
 100  *
 101  * \param kvm Pointer to the current kvm_context
 102  * \param phys_mem_bytes The amount of physical ram you want the VM to have
 103  * \param phys_mem This pointer will be set to point to the memory that
 104  * kvm_create allocates for physical RAM
 105  * \return 0 on success
 106  */
 107 int kvm_create(kvm_context_t kvm,
 108                unsigned long phys_mem_bytes,
 109                void **phys_mem);
 110
 111 /*!
 112  * \brief Start the VCPU
 113  *
 114  * This starts the VCPU and virtualization is started.\n
 115  * \n
 116  * This function will not return until any of these conditions are met:
 117  * - An IO/MMIO handler does not return "0"
 118  * - An exception that neither the guest OS, nor KVM can handle occurs
 119  *
 120  * \note This function will call the callbacks registered in kvm_init()
 121  * to emulate those functions
 122  * \note If you at any point want to interrupt the VCPU, kvm_run() will
 123  * listen to the EINTR signal. This allows you to simulate external interrupts
 124  * and asyncronous IO.
 125  *
 126  * \param kvm Pointer to the current kvm_context
 127  * \param vcpu Which virtual CPU should be started
 128  * \return 0 on success, but you really shouldn't expect this function to
 129  * return except for when an error has occured, or when you have sent it
 130  * an EINTR signal.
 131  */
 132 int kvm_run(kvm_context_t kvm, int vcpu);
 133
 134 /*!
 135  * \brief Read VCPU registers
 136  *
 137  * This gets the GP registers from the VCPU and outputs them
 138  * into a kvm_regs structure
 139  *
 140  * \note This function returns a \b copy of the VCPUs registers.\n
 141  * If you wish to modify the VCPUs GP registers, you should call kvm_set_regs()
 142  *
 143  * \param kvm Pointer to the current kvm_context
 144  * \param vcpu Which virtual CPU should get dumped
 145  * \param regs Pointer to a kvm_regs which will be populated with the VCPUs
 146  * registers values
 147  * \return 0 on success
 148  */
 149 int kvm_get_regs(kvm_context_t kvm, int vcpu, struct kvm_regs *regs);
 150
 151 /*!
 152  * \brief Write VCPU registers
 153  *
 154  * This sets the GP registers on the VCPU from a kvm_regs structure
 155  *
 156  * \note When this function returns, the regs pointer and the data it points to
 157  * can be discarded
 158  * \param kvm Pointer to the current kvm_context
 159  * \param vcpu Which virtual CPU should get dumped
 160  * \param regs Pointer to a kvm_regs which will be populated with the VCPUs
 161  * registers values
 162  * \return 0 on success
 163  */
 164 int kvm_set_regs(kvm_context_t kvm, int vcpu, struct kvm_regs *regs);
 165
 166 /*!
 167  * \brief Read VCPU system registers
 168  *
 169  * This gets the non-GP registers from the VCPU and outputs them
 170  * into a kvm_sregs structure
 171  *
 172  * \note This function returns a \b copy of the VCPUs registers.\n
 173  * If you wish to modify the VCPUs non-GP registers, you should call
 174  * kvm_set_sregs()
 175  *
 176  * \param kvm Pointer to the current kvm_context
 177  * \param vcpu Which virtual CPU should get dumped
 178  * \param regs Pointer to a kvm_sregs which will be populated with the VCPUs
 179  * registers values
 180  * \return 0 on success
 181  */
 182 int kvm_get_sregs(kvm_context_t kvm, int vcpu, struct kvm_sregs *regs);
 183
 184 /*!
 185  * \brief Write VCPU system registers
 186  *
 187  * This sets the non-GP registers on the VCPU from a kvm_sregs structure
 188  *
 189  * \note When this function returns, the regs pointer and the data it points to
 190  * can be discarded
 191  * \param kvm Pointer to the current kvm_context
 192  * \param vcpu Which virtual CPU should get dumped
 193  * \param regs Pointer to a kvm_sregs which will be populated with the VCPUs
 194  * registers values
 195  * \return 0 on success
 196  */
 197 int kvm_set_sregs(kvm_context_t kvm, int vcpu, struct kvm_sregs *regs);
 198
 199 struct kvm_msr_list *kvm_get_msr_list(kvm_context_t);
 200 int kvm_get_msrs(kvm_context_t, int vcpu, struct kvm_msr_entry *msrs, int n);
 201 int kvm_set_msrs(kvm_context_t, int vcpu, struct kvm_msr_entry *msrs, int n);
 202
 203 /*!
 204  * \brief Simulate an external vectored interrupt
 205  *
 206  * This allows you to simulate an external vectored interrupt.
 207  *
 208  * \param kvm Pointer to the current kvm_context
 209  * \param vcpu Which virtual CPU should get dumped
 210  * \param irq Vector number
 211  * \return 0 on success
 212  */
 213 int kvm_inject_irq(kvm_context_t kvm, int vcpu, unsigned irq);
 214 int kvm_guest_debug(kvm_context_t, int vcpu, struct kvm_debug_guest *dbg);
 215
 216 /*!
 217  * \brief Dump all VCPU information
 218  *
 219  * This dumps \b all the information that KVM has about a virtual CPU, namely:
 220  * - GP Registers
 221  * - System registers (selectors, descriptors, etc)
 222  * - VMCS Data
 223  * - MSRS
 224  * - Pending interrupts
 225  *
 226  * \param kvm Pointer to the current kvm_context
 227  * \param vcpu Which virtual CPU should get dumped
 228  * \return 0 on success
 229  */
 230 int kvm_dump_vcpu(kvm_context_t kvm, int vcpu);
 231
 232 /*!
 233  * \brief Dump VCPU registers
 234  *
 235  * This dumps some of the information that KVM has about a virtual CPU, namely:
 236  * - GP Registers
 237  *
 238  * A much more verbose version of this is available as kvm_dump_vcpu()
 239  *
 240  * \param kvm Pointer to the current kvm_context
 241  * \param vcpu Which virtual CPU should get dumped
 242  * \return 0 on success
 243  */
 244 void kvm_show_regs(kvm_context_t kvm, int vcpu);
 245
 246 void *kvm_create_phys_mem(kvm_context_t, unsigned long phys_start,
 247                           unsigned long len, int slot, int log, int writable);
 248 void kvm_destroy_phys_mem(kvm_context_t, unsigned long phys_start,
 249                           unsigned long len);
 250 void kvm_get_dirty_pages(kvm_context_t, int slot, void *buf);
 251
 252 #endif