kvm/user/kvmctl.h

   1 /** \file kvmctl.h
   2  * libkvm API
   3  */
   4
   5 #ifndef KVMCTL_H
   6 #define KVMCTL_H
   7
   8 #ifndef __user
   9 #define __user /* temporary, until installed via make headers_install */
  10 #endif
  11
  12 #include <linux/kvm.h>
  13 #include <stdint.h>
  14 #include <signal.h>
  15
  16 struct kvm_context;
  17
  18 typedef struct kvm_context *kvm_context_t;
  19
  20 /*!
  21  * \brief KVM callbacks structure
  22  *
  23  * This structure holds pointers to various functions that KVM will call
  24  * when it encounters something that cannot be virtualized, such as
  25  * accessing hardware devices via MMIO or regular IO.
  26  */
  27 struct kvm_callbacks {
  28         /// For 8bit IO reads from the guest (Usually when executing 'inb')
  29     int (*inb)(void *opaque, uint16_t addr, uint8_t *data);
  30         /// For 16bit IO reads from the guest (Usually when executing 'inw')
  31     int (*inw)(void *opaque, uint16_t addr, uint16_t *data);
  32         /// For 32bit IO reads from the guest (Usually when executing 'inl')
  33     int (*inl)(void *opaque, uint16_t addr, uint32_t *data);
  34         /// For 8bit IO writes from the guest (Usually when executing 'outb')
  35     int (*outb)(void *opaque, uint16_t addr, uint8_t data);
  36         /// For 16bit IO writes from the guest (Usually when executing 'outw')
  37     int (*outw)(void *opaque, uint16_t addr, uint16_t data);
  38         /// For 32bit IO writes from the guest (Usually when executing 'outl')
  39     int (*outl)(void *opaque, uint16_t addr, uint32_t data);
  40         /// For 8bit memory reads from unmapped memory (For MMIO devices)
  41     int (*readb)(void *opaque, uint64_t addr, uint8_t *data);
  42         /// For 16bit memory reads from unmapped memory (For MMIO devices)
  43     int (*readw)(void *opaque, uint64_t addr, uint16_t *data);
  44         /// For 32bit memory reads from unmapped memory (For MMIO devices)
  45     int (*readl)(void *opaque, uint64_t addr, uint32_t *data);
  46         /// For 64bit memory reads from unmapped memory (For MMIO devices)
  47     int (*readq)(void *opaque, uint64_t addr, uint64_t *data);
  48         /// For 8bit memory writes to unmapped memory (For MMIO devices)
  49     int (*writeb)(void *opaque, uint64_t addr, uint8_t data);
  50         /// For 16bit memory writes to unmapped memory (For MMIO devices)
  51     int (*writew)(void *opaque, uint64_t addr, uint16_t data);
  52         /// For 32bit memory writes to unmapped memory (For MMIO devices)
  53     int (*writel)(void *opaque, uint64_t addr, uint32_t data);
  54         /// For 64bit memory writes to unmapped memory (For MMIO devices)
  55     int (*writeq)(void *opaque, uint64_t addr, uint64_t data);
  56     int (*debug)(void *opaque, int vcpu);
  57         /*!
  58          * \brief Called when the VCPU issues an 'hlt' instruction.
  59          *
  60          * Typically, you should yeild here to prevent 100% CPU utilization
  61          * on the host CPU.
  62          */
  63     int (*halt)(void *opaque, int vcpu);
  64     int (*shutdown)(void *opaque, int vcpu);
  65     int (*io_window)(void *opaque);
  66     int (*try_push_interrupts)(void *opaque);
  67     void (*post_kvm_run)(void *opaque, int vcpu);
  68     void (*pre_kvm_run)(void *opaque, int vcpu);
  69 };
  70
  71 /*!
  72  * \brief Create new KVM context
  73  *
  74  * This creates a new kvm_context. A KVM context is a small area of data that
  75  * holds information about the KVM instance that gets created by this call.\n
  76  * This should always be your first call to KVM.
  77  *
  78  * \param callbacks Pointer to a valid kvm_callbacks structure
  79  * \param opaque Not used
  80  * \return NULL on failure
  81  */
  82 kvm_context_t kvm_init(struct kvm_callbacks *callbacks,
  83                        void *opaque);
  84
  85 /*!
  86  * \brief Cleanup the KVM context
  87  *
  88  * Should always be called when closing down KVM.\n
  89  * Exception: If kvm_init() fails, this function should not be called, as the
  90  * context would be invalid
  91  *
  92  * \param kvm Pointer to the kvm_context that is to be freed
  93  */
  94 void kvm_finalize(kvm_context_t kvm);
  95
  96 /*!
  97  * \brief Create new virtual machine
  98  *
  99  * This creates a new virtual machine, maps physical RAM to it, and creates a
 100  * virtual CPU for it.\n
 101  * \n
 102  * Memory gets mapped for addresses 0->0xA0000, 0xC0000->phys_mem_bytes
 103  *
 104  * \param kvm Pointer to the current kvm_context
 105  * \param phys_mem_bytes The amount of physical ram you want the VM to have
 106  * \param phys_mem This pointer will be set to point to the memory that
 107  * kvm_create allocates for physical RAM
 108  * \return 0 on success
 109  */
 110 int kvm_create(kvm_context_t kvm,
 111                unsigned long phys_mem_bytes,
 112                void **phys_mem);
 113 /*!
 114  * \brief Create a new virtual cpu
 115  *
 116  * This creates a new virtual cpu (the first vcpu is created by kvm_create()).
 117  * Should be called from a thread dedicated to the vcpu.
 118  *
 119  * \param kvm kvm context
 120  * \param slot vcpu number (> 0)
 121  * \return 0 on success, -errno on failure
 122  */
 123 int kvm_create_vcpu(kvm_context_t kvm, int slot);
 124
 125 /*!
 126  * \brief Start the VCPU
 127  *
 128  * This starts the VCPU and virtualization is started.\n
 129  * \n
 130  * This function will not return until any of these conditions are met:
 131  * - An IO/MMIO handler does not return "0"
 132  * - An exception that neither the guest OS, nor KVM can handle occurs
 133  *
 134  * \note This function will call the callbacks registered in kvm_init()
 135  * to emulate those functions
 136  * \note If you at any point want to interrupt the VCPU, kvm_run() will
 137  * listen to the EINTR signal. This allows you to simulate external interrupts
 138  * and asyncronous IO.
 139  *
 140  * \param kvm Pointer to the current kvm_context
 141  * \param vcpu Which virtual CPU should be started
 142  * \return 0 on success, but you really shouldn't expect this function to
 143  * return except for when an error has occured, or when you have sent it
 144  * an EINTR signal.
 145  */
 146 int kvm_run(kvm_context_t kvm, int vcpu);
 147
 148 /*!
 149  * \brief Get interrupt flag from on last exit to userspace
 150  *
 151  * This gets the CPU interrupt flag as it was on the last exit to userspace.
 152  *
 153  * \param kvm Pointer to the current kvm_context
 154  * \param vcpu Which virtual CPU should get dumped
 155  * \return interrupt flag value (0 or 1)
 156  */
 157 int kvm_get_interrupt_flag(kvm_context_t kvm, int vcpu);
 158
 159 /*!
 160  * \brief Get the value of the APIC_BASE msr as of last exit to userspace
 161  *
 162  * This gets the APIC_BASE msr as it was on the last exit to userspace.
 163  *
 164  * \param kvm Pointer to the current kvm_context
 165  * \param vcpu Which virtual CPU should get dumped
 166  * \return APIC_BASE msr contents
 167  */
 168 uint64_t kvm_get_apic_base(kvm_context_t kvm, int vcpu);
 169
 170 /*!
 171  * \brief Check if a vcpu is ready for interrupt injection
 172  *
 173  * This checks if vcpu interrupts are not masked by mov ss or sti.
 174  *
 175  * \param kvm Pointer to the current kvm_context
 176  * \param vcpu Which virtual CPU should get dumped
 177  * \return boolean indicating interrupt injection readiness
 178  */
 179 int kvm_is_ready_for_interrupt_injection(kvm_context_t kvm, int vcpu);
 180
 181 /*!
 182  * \brief Set up cr8 for next time the vcpu is executed
 183  *
 184  * This is a fast setter for cr8, which will be applied when the
 185  * vcpu next enters guest mode.
 186  *
 187  * \param kvm Pointer to the current kvm_context
 188  * \param vcpu Which virtual CPU should get dumped
 189  * \param cr8 next cr8 value
 190  */
 191 void kvm_set_cr8(kvm_context_t kvm, int vcpu, uint64_t cr8);
 192
 193 /*!
 194  * \brief Read VCPU registers
 195  *
 196  * This gets the GP registers from the VCPU and outputs them
 197  * into a kvm_regs structure
 198  *
 199  * \note This function returns a \b copy of the VCPUs registers.\n
 200  * If you wish to modify the VCPUs GP registers, you should call kvm_set_regs()
 201  *
 202  * \param kvm Pointer to the current kvm_context
 203  * \param vcpu Which virtual CPU should get dumped
 204  * \param regs Pointer to a kvm_regs which will be populated with the VCPUs
 205  * registers values
 206  * \return 0 on success
 207  */
 208 int kvm_get_regs(kvm_context_t kvm, int vcpu, struct kvm_regs *regs);
 209
 210 /*!
 211  * \brief Write VCPU registers
 212  *
 213  * This sets the GP registers on the VCPU from a kvm_regs structure
 214  *
 215  * \note When this function returns, the regs pointer and the data it points to
 216  * can be discarded
 217  * \param kvm Pointer to the current kvm_context
 218  * \param vcpu Which virtual CPU should get dumped
 219  * \param regs Pointer to a kvm_regs which will be populated with the VCPUs
 220  * registers values
 221  * \return 0 on success
 222  */
 223 int kvm_set_regs(kvm_context_t kvm, int vcpu, struct kvm_regs *regs);
 224 /*!
 225  * \brief Read VCPU fpu registers
 226  *
 227  * This gets the FPU registers from the VCPU and outputs them
 228  * into a kvm_fpu structure
 229  *
 230  * \note This function returns a \b copy of the VCPUs registers.\n
 231  * If you wish to modify the VCPU FPU registers, you should call kvm_set_fpu()
 232  *
 233  * \param kvm Pointer to the current kvm_context
 234  * \param vcpu Which virtual CPU should get dumped
 235  * \param fpu Pointer to a kvm_fpu which will be populated with the VCPUs
 236  * fpu registers values
 237  * \return 0 on success
 238  */
 239 int kvm_get_fpu(kvm_context_t kvm, int vcpu, struct kvm_fpu *fpu);
 240
 241 /*!
 242  * \brief Write VCPU fpu registers
 243  *
 244  * This sets the FPU registers on the VCPU from a kvm_fpu structure
 245  *
 246  * \note When this function returns, the fpu pointer and the data it points to
 247  * can be discarded
 248  * \param kvm Pointer to the current kvm_context
 249  * \param vcpu Which virtual CPU should get dumped
 250  * \param fpu Pointer to a kvm_fpu which holds the new vcpu fpu state
 251  * \return 0 on success
 252  */
 253 int kvm_set_fpu(kvm_context_t kvm, int vcpu, struct kvm_fpu *fpu);
 254
 255 /*!
 256  * \brief Read VCPU system registers
 257  *
 258  * This gets the non-GP registers from the VCPU and outputs them
 259  * into a kvm_sregs structure
 260  *
 261  * \note This function returns a \b copy of the VCPUs registers.\n
 262  * If you wish to modify the VCPUs non-GP registers, you should call
 263  * kvm_set_sregs()
 264  *
 265  * \param kvm Pointer to the current kvm_context
 266  * \param vcpu Which virtual CPU should get dumped
 267  * \param regs Pointer to a kvm_sregs which will be populated with the VCPUs
 268  * registers values
 269  * \return 0 on success
 270  */
 271 int kvm_get_sregs(kvm_context_t kvm, int vcpu, struct kvm_sregs *regs);
 272
 273 /*!
 274  * \brief Write VCPU system registers
 275  *
 276  * This sets the non-GP registers on the VCPU from a kvm_sregs structure
 277  *
 278  * \note When this function returns, the regs pointer and the data it points to
 279  * can be discarded
 280  * \param kvm Pointer to the current kvm_context
 281  * \param vcpu Which virtual CPU should get dumped
 282  * \param regs Pointer to a kvm_sregs which will be populated with the VCPUs
 283  * registers values
 284  * \return 0 on success
 285  */
 286 int kvm_set_sregs(kvm_context_t kvm, int vcpu, struct kvm_sregs *regs);
 287
 288 struct kvm_msr_list *kvm_get_msr_list(kvm_context_t);
 289 int kvm_get_msrs(kvm_context_t, int vcpu, struct kvm_msr_entry *msrs, int n);
 290 int kvm_set_msrs(kvm_context_t, int vcpu, struct kvm_msr_entry *msrs, int n);
 291
 292 /*!
 293  * \brief Simulate an external vectored interrupt
 294  *
 295  * This allows you to simulate an external vectored interrupt.
 296  *
 297  * \param kvm Pointer to the current kvm_context
 298  * \param vcpu Which virtual CPU should get dumped
 299  * \param irq Vector number
 300  * \return 0 on success
 301  */
 302 int kvm_inject_irq(kvm_context_t kvm, int vcpu, unsigned irq);
 303
 304 int kvm_guest_debug(kvm_context_t, int vcpu, struct kvm_debug_guest *dbg);
 305
 306 /*!
 307  * \brief Setup a vcpu's cpuid instruction emulation
 308  *
 309  * Set up a table of cpuid function to cpuid outputs.\n
 310  *
 311  * \param kvm Pointer to the current kvm_context
 312  * \param vcpu Which virtual CPU should be initialized
 313  * \param nent number of entries to be installed
 314  * \param entries cpuid function entries table
 315  * \return 0 on success, or -errno on error
 316  */
 317 int kvm_setup_cpuid(kvm_context_t kvm, int vcpu, int nent,
 318                     struct kvm_cpuid_entry *entries);
 319
 320 /*!
 321  * \brief Set a vcpu's signal mask for guest mode
 322  *
 323  * A vcpu can have different signals blocked in guest mode and user mode.
 324  * This allows guest execution to be interrupted on a signal, without requiring
 325  * that the signal be delivered to a signal handler (the signal can be
 326  * dequeued using sigwait(2).
 327  *
 328  * \param kvm Pointer to the current kvm_context
 329  * \param vcpu Which virtual CPU should be initialized
 330  * \param sigset signal mask for guest mode
 331  * \return 0 on success, or -errno on error
 332  */
 333 int kvm_set_signal_mask(kvm_context_t kvm, int vcpu, const sigset_t *sigset);
 334
 335 /*!
 336  * \brief Dump all VCPU information
 337  *
 338  * This dumps \b all the information that KVM has about a virtual CPU, namely:
 339  * - GP Registers
 340  * - System registers (selectors, descriptors, etc)
 341  * - VMCS Data
 342  * - MSRS
 343  * - Pending interrupts
 344  *
 345  * \param kvm Pointer to the current kvm_context
 346  * \param vcpu Which virtual CPU should get dumped
 347  * \return 0 on success
 348  */
 349 int kvm_dump_vcpu(kvm_context_t kvm, int vcpu);
 350
 351 /*!
 352  * \brief Dump VCPU registers
 353  *
 354  * This dumps some of the information that KVM has about a virtual CPU, namely:
 355  * - GP Registers
 356  *
 357  * A much more verbose version of this is available as kvm_dump_vcpu()
 358  *
 359  * \param kvm Pointer to the current kvm_context
 360  * \param vcpu Which virtual CPU should get dumped
 361  * \return 0 on success
 362  */
 363 void kvm_show_regs(kvm_context_t kvm, int vcpu);
 364
 365 void *kvm_create_phys_mem(kvm_context_t, unsigned long phys_start,
 366                           unsigned long len, int slot, int log, int writable);
 367 void kvm_destroy_phys_mem(kvm_context_t, unsigned long phys_start,
 368                           unsigned long len);
 369 int kvm_get_dirty_pages(kvm_context_t, int slot, void *buf);
 370
 371
 372 /*!
 373  * \brief Create a memory alias
 374  *
 375  * Aliases a portion of physical memory to another portion.  If the guest
 376  * accesses the alias region, it will behave exactly as if it accessed
 377  * the target memory.
 378  */
 379 int kvm_create_memory_alias(kvm_context_t, int slot,
 380                             uint64_t phys_start, uint64_t len,
 381                             uint64_t target_phys);
 382
 383 /*!
 384  * \brief Destroy a memory alias
 385  *
 386  * Removes an alias created with kvm_create_memory_alias().
 387  */
 388 int kvm_destroy_memory_alias(kvm_context_t, int slot);
 389
 390 /*!
 391  * \brief Get a bitmap of guest ram pages which are allocated to the guest.
 392  *
 393  * \param kvm Pointer to the current kvm_context
 394  * \param slot Memory slot number
 395  * \param bitmap Long aligned address of a big enough bitmap (one bit per page)
 396  */
 397 int kvm_get_mem_map(kvm_context_t kvm, int slot, void *bitmap);
 398
 399 /*!
 400  * \brief Enable dirty-pages-logging for all memory regions
 401  *
 402  * \param kvm Pointer to the current kvm_context
 403  */
 404 int kvm_dirty_pages_log_enable_all(kvm_context_t kvm);
 405
 406 /*!
 407  * \brief Disable dirty-page-logging for some memory regions
 408  *
 409  * Disable dirty-pages-logging for those memory regions that were
 410  * created with dirty-page-logging disabled.
 411  *
 412  * \param kvm Pointer to the current kvm_context
 413  */
 414 int kvm_dirty_pages_log_reset(kvm_context_t kvm);
 415
 416 #endif