kvm/libkvm/libkvm.h

   1 /** \file libkvm.h
   2  * libkvm API
   3  */
   4
   5 #ifndef LIBKVM_H
   6 #define LIBKVM_H
   7
   8 #include <stdint.h>
   9
  10 #ifndef __user
  11 #define __user /* temporary, until installed via make headers_install */
  12 #endif
  13
  14 #include <linux/kvm.h>
  15
  16 #include <signal.h>
  17
  18 struct kvm_context;
  19
  20 typedef struct kvm_context *kvm_context_t;
  21
  22 #if defined(__x86_64__) || defined(__i386__)
  23 struct kvm_msr_list *kvm_get_msr_list(kvm_context_t);
  24 int kvm_get_msrs(kvm_context_t, int vcpu, struct kvm_msr_entry *msrs, int n);
  25 int kvm_set_msrs(kvm_context_t, int vcpu, struct kvm_msr_entry *msrs, int n);
  26 #endif
  27
  28 /*!
  29  * \brief KVM callbacks structure
  30  *
  31  * This structure holds pointers to various functions that KVM will call
  32  * when it encounters something that cannot be virtualized, such as
  33  * accessing hardware devices via MMIO or regular IO.
  34  */
  35 struct kvm_callbacks {
  36         /// For 8bit IO reads from the guest (Usually when executing 'inb')
  37     int (*inb)(void *opaque, uint16_t addr, uint8_t *data);
  38         /// For 16bit IO reads from the guest (Usually when executing 'inw')
  39     int (*inw)(void *opaque, uint16_t addr, uint16_t *data);
  40         /// For 32bit IO reads from the guest (Usually when executing 'inl')
  41     int (*inl)(void *opaque, uint16_t addr, uint32_t *data);
  42         /// For 8bit IO writes from the guest (Usually when executing 'outb')
  43     int (*outb)(void *opaque, uint16_t addr, uint8_t data);
  44         /// For 16bit IO writes from the guest (Usually when executing 'outw')
  45     int (*outw)(void *opaque, uint16_t addr, uint16_t data);
  46         /// For 32bit IO writes from the guest (Usually when executing 'outl')
  47     int (*outl)(void *opaque, uint16_t addr, uint32_t data);
  48         /// generic memory reads to unmapped memory (For MMIO devices)
  49     int (*mmio_read)(void *opaque, uint64_t addr, uint8_t *data,
  50                                         int len);
  51         /// generic memory writes to unmapped memory (For MMIO devices)
  52     int (*mmio_write)(void *opaque, uint64_t addr, uint8_t *data,
  53                                         int len);
  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 (*shutdown)(void *opaque, int vcpu);
  63     int (*io_window)(void *opaque);
  64     int (*try_push_interrupts)(void *opaque);
  65     void (*post_kvm_run)(void *opaque, int vcpu);
  66     int (*pre_kvm_run)(void *opaque, int vcpu);
  67     int (*tpr_access)(void *opaque, int vcpu, uint64_t rip, int is_write);
  68 #if defined(__powerpc__)
  69     int (*powerpc_dcr_read)(kvm_context_t kvm, uint32_t dcrn, uint32_t *data);
  70     int (*powerpc_dcr_write)(kvm_context_t kvm, uint32_t dcrn, uint32_t data);
  71 #endif
  72 };
  73
  74 /*!
  75  * \brief Create new KVM context
  76  *
  77  * This creates a new kvm_context. A KVM context is a small area of data that
  78  * holds information about the KVM instance that gets created by this call.\n
  79  * This should always be your first call to KVM.
  80  *
  81  * \param callbacks Pointer to a valid kvm_callbacks structure
  82  * \param opaque Not used
  83  * \return NULL on failure
  84  */
  85 kvm_context_t kvm_init(struct kvm_callbacks *callbacks,
  86                        void *opaque);
  87
  88 /*!
  89  * \brief Cleanup the KVM context
  90  *
  91  * Should always be called when closing down KVM.\n
  92  * Exception: If kvm_init() fails, this function should not be called, as the
  93  * context would be invalid
  94  *
  95  * \param kvm Pointer to the kvm_context that is to be freed
  96  */
  97 void kvm_finalize(kvm_context_t kvm);
  98
  99 /*!
 100  * \brief Disable the in-kernel IRQCHIP creation
 101  *
 102  * In-kernel irqchip is enabled by default. If userspace irqchip is to be used,
 103  * this should be called prior to kvm_create().
 104  *
 105  * \param kvm Pointer to the kvm_context
 106  */
 107 void kvm_disable_irqchip_creation(kvm_context_t kvm);
 108
 109 /*!
 110  * \brief Create new virtual machine
 111  *
 112  * This creates a new virtual machine, maps physical RAM to it, and creates a
 113  * virtual CPU for it.\n
 114  * \n
 115  * Memory gets mapped for addresses 0->0xA0000, 0xC0000->phys_mem_bytes
 116  *
 117  * \param kvm Pointer to the current kvm_context
 118  * \param phys_mem_bytes The amount of physical ram you want the VM to have
 119  * \param phys_mem This pointer will be set to point to the memory that
 120  * kvm_create allocates for physical RAM
 121  * \return 0 on success
 122  */
 123 int kvm_create(kvm_context_t kvm,
 124                unsigned long phys_mem_bytes,
 125                void **phys_mem);
 126 int kvm_create_vm(kvm_context_t kvm);
 127 int kvm_check_extension(kvm_context_t kvm, int ext);
 128 void kvm_create_irqchip(kvm_context_t kvm);
 129
 130 /*!
 131  * \brief Create a new virtual cpu
 132  *
 133  * This creates a new virtual cpu (the first vcpu is created by kvm_create()).
 134  * Should be called from a thread dedicated to the vcpu.
 135  *
 136  * \param kvm kvm context
 137  * \param slot vcpu number (> 0)
 138  * \return 0 on success, -errno on failure
 139  */
 140 int kvm_create_vcpu(kvm_context_t kvm, int slot);
 141
 142 /*!
 143  * \brief Start the VCPU
 144  *
 145  * This starts the VCPU and virtualization is started.\n
 146  * \n
 147  * This function will not return until any of these conditions are met:
 148  * - An IO/MMIO handler does not return "0"
 149  * - An exception that neither the guest OS, nor KVM can handle occurs
 150  *
 151  * \note This function will call the callbacks registered in kvm_init()
 152  * to emulate those functions
 153  * \note If you at any point want to interrupt the VCPU, kvm_run() will
 154  * listen to the EINTR signal. This allows you to simulate external interrupts
 155  * and asyncronous IO.
 156  *
 157  * \param kvm Pointer to the current kvm_context
 158  * \param vcpu Which virtual CPU should be started
 159  * \return 0 on success, but you really shouldn't expect this function to
 160  * return except for when an error has occured, or when you have sent it
 161  * an EINTR signal.
 162  */
 163 int kvm_run(kvm_context_t kvm, int vcpu);
 164
 165 /*!
 166  * \brief Get interrupt flag from on last exit to userspace
 167  *
 168  * This gets the CPU interrupt flag as it was on the last exit to userspace.
 169  *
 170  * \param kvm Pointer to the current kvm_context
 171  * \param vcpu Which virtual CPU should get dumped
 172  * \return interrupt flag value (0 or 1)
 173  */
 174 int kvm_get_interrupt_flag(kvm_context_t kvm, int vcpu);
 175
 176 /*!
 177  * \brief Get the value of the APIC_BASE msr as of last exit to userspace
 178  *
 179  * This gets the APIC_BASE msr as it was on the last exit to userspace.
 180  *
 181  * \param kvm Pointer to the current kvm_context
 182  * \param vcpu Which virtual CPU should get dumped
 183  * \return APIC_BASE msr contents
 184  */
 185 uint64_t kvm_get_apic_base(kvm_context_t kvm, int vcpu);
 186
 187 /*!
 188  * \brief Check if a vcpu is ready for interrupt injection
 189  *
 190  * This checks if vcpu interrupts are not masked by mov ss or sti.
 191  *
 192  * \param kvm Pointer to the current kvm_context
 193  * \param vcpu Which virtual CPU should get dumped
 194  * \return boolean indicating interrupt injection readiness
 195  */
 196 int kvm_is_ready_for_interrupt_injection(kvm_context_t kvm, int vcpu);
 197
 198 /*!
 199  * \brief Read VCPU registers
 200  *
 201  * This gets the GP registers from the VCPU and outputs them
 202  * into a kvm_regs structure
 203  *
 204  * \note This function returns a \b copy of the VCPUs registers.\n
 205  * If you wish to modify the VCPUs GP registers, you should call kvm_set_regs()
 206  *
 207  * \param kvm Pointer to the current kvm_context
 208  * \param vcpu Which virtual CPU should get dumped
 209  * \param regs Pointer to a kvm_regs which will be populated with the VCPUs
 210  * registers values
 211  * \return 0 on success
 212  */
 213 int kvm_get_regs(kvm_context_t kvm, int vcpu, struct kvm_regs *regs);
 214
 215 /*!
 216  * \brief Write VCPU registers
 217  *
 218  * This sets the GP registers on the VCPU from a kvm_regs structure
 219  *
 220  * \note When this function returns, the regs pointer and the data it points to
 221  * can be discarded
 222  * \param kvm Pointer to the current kvm_context
 223  * \param vcpu Which virtual CPU should get dumped
 224  * \param regs Pointer to a kvm_regs which will be populated with the VCPUs
 225  * registers values
 226  * \return 0 on success
 227  */
 228 int kvm_set_regs(kvm_context_t kvm, int vcpu, struct kvm_regs *regs);
 229 /*!
 230  * \brief Read VCPU fpu registers
 231  *
 232  * This gets the FPU registers from the VCPU and outputs them
 233  * into a kvm_fpu structure
 234  *
 235  * \note This function returns a \b copy of the VCPUs registers.\n
 236  * If you wish to modify the VCPU FPU registers, you should call kvm_set_fpu()
 237  *
 238  * \param kvm Pointer to the current kvm_context
 239  * \param vcpu Which virtual CPU should get dumped
 240  * \param fpu Pointer to a kvm_fpu which will be populated with the VCPUs
 241  * fpu registers values
 242  * \return 0 on success
 243  */
 244 int kvm_get_fpu(kvm_context_t kvm, int vcpu, struct kvm_fpu *fpu);
 245
 246 /*!
 247  * \brief Write VCPU fpu registers
 248  *
 249  * This sets the FPU registers on the VCPU from a kvm_fpu structure
 250  *
 251  * \note When this function returns, the fpu pointer and the data it points to
 252  * can be discarded
 253  * \param kvm Pointer to the current kvm_context
 254  * \param vcpu Which virtual CPU should get dumped
 255  * \param fpu Pointer to a kvm_fpu which holds the new vcpu fpu state
 256  * \return 0 on success
 257  */
 258 int kvm_set_fpu(kvm_context_t kvm, int vcpu, struct kvm_fpu *fpu);
 259
 260 /*!
 261  * \brief Read VCPU system registers
 262  *
 263  * This gets the non-GP registers from the VCPU and outputs them
 264  * into a kvm_sregs structure
 265  *
 266  * \note This function returns a \b copy of the VCPUs registers.\n
 267  * If you wish to modify the VCPUs non-GP registers, you should call
 268  * kvm_set_sregs()
 269  *
 270  * \param kvm Pointer to the current kvm_context
 271  * \param vcpu Which virtual CPU should get dumped
 272  * \param regs Pointer to a kvm_sregs which will be populated with the VCPUs
 273  * registers values
 274  * \return 0 on success
 275  */
 276 int kvm_get_sregs(kvm_context_t kvm, int vcpu, struct kvm_sregs *regs);
 277
 278 /*!
 279  * \brief Write VCPU system registers
 280  *
 281  * This sets the non-GP registers on the VCPU from a kvm_sregs structure
 282  *
 283  * \note When this function returns, the regs pointer and the data it points to
 284  * can be discarded
 285  * \param kvm Pointer to the current kvm_context
 286  * \param vcpu Which virtual CPU should get dumped
 287  * \param regs Pointer to a kvm_sregs which will be populated with the VCPUs
 288  * registers values
 289  * \return 0 on success
 290  */
 291 int kvm_set_sregs(kvm_context_t kvm, int vcpu, struct kvm_sregs *regs);
 292
 293 /*!
 294  * \brief Simulate an external vectored interrupt
 295  *
 296  * This allows you to simulate an external vectored interrupt.
 297  *
 298  * \param kvm Pointer to the current kvm_context
 299  * \param vcpu Which virtual CPU should get dumped
 300  * \param irq Vector number
 301  * \return 0 on success
 302  */
 303 int kvm_inject_irq(kvm_context_t kvm, int vcpu, unsigned irq);
 304
 305 int kvm_guest_debug(kvm_context_t, int vcpu, struct kvm_debug_guest *dbg);
 306
 307 #if defined(__i386__) || defined(__x86_64__)
 308 /*!
 309  * \brief Setup a vcpu's cpuid instruction emulation
 310  *
 311  * Set up a table of cpuid function to cpuid outputs.\n
 312  *
 313  * \param kvm Pointer to the current kvm_context
 314  * \param vcpu Which virtual CPU should be initialized
 315  * \param nent number of entries to be installed
 316  * \param entries cpuid function entries table
 317  * \return 0 on success, or -errno on error
 318  */
 319 int kvm_setup_cpuid(kvm_context_t kvm, int vcpu, int nent,
 320                     struct kvm_cpuid_entry *entries);
 321
 322 /*!
 323  * \brief Setting the number of shadow pages to be allocated to the vm
 324  *
 325  * \param kvm pointer to kvm_context
 326  * \param nrshadow_pages number of pages to be allocated
 327  */
 328 int kvm_set_shadow_pages(kvm_context_t kvm, unsigned int nrshadow_pages);
 329
 330 /*!
 331  * \breif Getting the number of shadow pages that are allocated to the vm
 332  *
 333  * \param kvm pointer to kvm_context
 334  * \param nrshadow_pages number of pages to be allocated
 335  */
 336 int kvm_get_shadow_pages(kvm_context_t kvm , unsigned int *nrshadow_pages);
 337
 338 /*!
 339  * \brief Set up cr8 for next time the vcpu is executed
 340  *
 341  * This is a fast setter for cr8, which will be applied when the
 342  * vcpu next enters guest mode.
 343  *
 344  * \param kvm Pointer to the current kvm_context
 345  * \param vcpu Which virtual CPU should get dumped
 346  * \param cr8 next cr8 value
 347  */
 348 void kvm_set_cr8(kvm_context_t kvm, int vcpu, uint64_t cr8);
 349
 350 /*!
 351  * \brief Get cr8 for sync tpr in qemu apic emulation
 352  *
 353  * This is a getter for cr8, which used to sync with the tpr in qemu
 354  * apic emualtion.
 355  *
 356  * \param kvm Pointer to the current kvm_context
 357  * \param vcpu Which virtual CPU should get dumped
 358  */
 359 __u64 kvm_get_cr8(kvm_context_t kvm, int vcpu);
 360 #endif
 361
 362 /*!
 363  * \brief Set a vcpu's signal mask for guest mode
 364  *
 365  * A vcpu can have different signals blocked in guest mode and user mode.
 366  * This allows guest execution to be interrupted on a signal, without requiring
 367  * that the signal be delivered to a signal handler (the signal can be
 368  * dequeued using sigwait(2).
 369  *
 370  * \param kvm Pointer to the current kvm_context
 371  * \param vcpu Which virtual CPU should be initialized
 372  * \param sigset signal mask for guest mode
 373  * \return 0 on success, or -errno on error
 374  */
 375 int kvm_set_signal_mask(kvm_context_t kvm, int vcpu, const sigset_t *sigset);
 376
 377 /*!
 378  * \brief Dump all VCPU information
 379  *
 380  * This dumps \b all the information that KVM has about a virtual CPU, namely:
 381  * - GP Registers
 382  * - System registers (selectors, descriptors, etc)
 383  * - VMCS Data
 384  * - MSRS
 385  * - Pending interrupts
 386  *
 387  * \param kvm Pointer to the current kvm_context
 388  * \param vcpu Which virtual CPU should get dumped
 389  * \return 0 on success
 390  */
 391 int kvm_dump_vcpu(kvm_context_t kvm, int vcpu);
 392
 393 /*!
 394  * \brief Dump VCPU registers
 395  *
 396  * This dumps some of the information that KVM has about a virtual CPU, namely:
 397  * - GP Registers
 398  *
 399  * A much more verbose version of this is available as kvm_dump_vcpu()
 400  *
 401  * \param kvm Pointer to the current kvm_context
 402  * \param vcpu Which virtual CPU should get dumped
 403  * \return 0 on success
 404  */
 405 void kvm_show_regs(kvm_context_t kvm, int vcpu);
 406
 407
 408 void *kvm_create_phys_mem(kvm_context_t, unsigned long phys_start,
 409                           unsigned long len, int log, int writable);
 410 void kvm_destroy_phys_mem(kvm_context_t, unsigned long phys_start,
 411                           unsigned long len);
 412 int kvm_is_intersecting_mem(kvm_context_t kvm, unsigned long phys_start);
 413 int kvm_is_allocated_mem(kvm_context_t kvm, unsigned long phys_start,
 414                          unsigned long len);
 415 int kvm_create_mem_hole(kvm_context_t kvm, unsigned long phys_start,
 416                         unsigned long len);
 417 int kvm_register_userspace_phys_mem(kvm_context_t kvm,
 418                         unsigned long phys_start, void *userspace_addr,
 419                         unsigned long len, int log);
 420 int kvm_get_dirty_pages(kvm_context_t, unsigned long phys_addr, void *buf);
 421 int kvm_get_dirty_pages_range(kvm_context_t kvm, unsigned long phys_addr,
 422                               unsigned long end_addr, void *buf, void*opaque,
 423                               int (*cb)(unsigned long start, unsigned long len,
 424                                         void*bitmap, void *opaque));
 425
 426 /*!
 427  * \brief Create a memory alias
 428  *
 429  * Aliases a portion of physical memory to another portion.  If the guest
 430  * accesses the alias region, it will behave exactly as if it accessed
 431  * the target memory.
 432  */
 433 int kvm_create_memory_alias(kvm_context_t, uint64_t phys_addr,
 434                             uint64_t phys_start, uint64_t len,
 435                             uint64_t target_phys);
 436
 437 /*!
 438  * \brief Destroy a memory alias
 439  *
 440  * Removes an alias created with kvm_create_memory_alias().
 441  */
 442 int kvm_destroy_memory_alias(kvm_context_t, uint64_t phys_addr);
 443
 444 /*!
 445  * \brief Get a bitmap of guest ram pages which are allocated to the guest.
 446  *
 447  * \param kvm Pointer to the current kvm_context
 448  * \param phys_addr Memory slot phys addr
 449  * \param bitmap Long aligned address of a big enough bitmap (one bit per page)
 450  */
 451 int kvm_get_mem_map(kvm_context_t kvm, unsigned long phys_addr, void *bitmap);
 452 int kvm_get_mem_map_range(kvm_context_t kvm, unsigned long phys_addr,
 453                            unsigned long len, void *buf, void *opaque,
 454                            int (*cb)(unsigned long start,unsigned long len,
 455                                      void* bitmap, void* opaque));
 456 int kvm_set_irq_level(kvm_context_t kvm, int irq, int level);
 457
 458 /*!
 459  * \brief Enable dirty-pages-logging for all memory regions
 460  *
 461  * \param kvm Pointer to the current kvm_context
 462  */
 463 int kvm_dirty_pages_log_enable_all(kvm_context_t kvm);
 464
 465 /*!
 466  * \brief Disable dirty-page-logging for some memory regions
 467  *
 468  * Disable dirty-pages-logging for those memory regions that were
 469  * created with dirty-page-logging disabled.
 470  *
 471  * \param kvm Pointer to the current kvm_context
 472  */
 473 int kvm_dirty_pages_log_reset(kvm_context_t kvm);
 474
 475 /*!
 476  * \brief Query whether in kernel irqchip is used
 477  *
 478  * \param kvm Pointer to the current kvm_context
 479  */
 480 int kvm_irqchip_in_kernel(kvm_context_t kvm);
 481
 482 #ifdef KVM_CAP_IRQCHIP
 483 /*!
 484  * \brief Dump in kernel IRQCHIP contents
 485  *
 486  * Dump one of the in kernel irq chip devices, including PIC (master/slave)
 487  * and IOAPIC into a kvm_irqchip structure
 488  *
 489  * \param kvm Pointer to the current kvm_context
 490  * \param chip The irq chip device to be dumped
 491  */
 492 int kvm_get_irqchip(kvm_context_t kvm, struct kvm_irqchip *chip);
 493
 494 /*!
 495  * \brief Set in kernel IRQCHIP contents
 496  *
 497  * Write one of the in kernel irq chip devices, including PIC (master/slave)
 498  * and IOAPIC
 499  *
 500  *
 501  * \param kvm Pointer to the current kvm_context
 502  * \param chip THe irq chip device to be written
 503  */
 504 int kvm_set_irqchip(kvm_context_t kvm, struct kvm_irqchip *chip);
 505
 506 #if defined(__i386__) || defined(__x86_64__)
 507 /*!
 508  * \brief Get in kernel local APIC for vcpu
 509  *
 510  * Save the local apic state including the timer of a virtual CPU
 511  *
 512  * \param kvm Pointer to the current kvm_context
 513  * \param vcpu Which virtual CPU should be accessed
 514  * \param s Local apic state of the specific virtual CPU
 515  */
 516 int kvm_get_lapic(kvm_context_t kvm, int vcpu, struct kvm_lapic_state *s);
 517
 518 /*!
 519  * \brief Set in kernel local APIC for vcpu
 520  *
 521  * Restore the local apic state including the timer of a virtual CPU
 522  *
 523  * \param kvm Pointer to the current kvm_context
 524  * \param vcpu Which virtual CPU should be accessed
 525  * \param s Local apic state of the specific virtual CPU
 526  */
 527 int kvm_set_lapic(kvm_context_t kvm, int vcpu, struct kvm_lapic_state *s);
 528 #endif
 529
 530 #endif
 531
 532 #ifdef KVM_CAP_VAPIC
 533
 534 /*!
 535  * \brief Enable kernel tpr access reporting
 536  *
 537  * When tpr access reporting is enabled, the kernel will call the
 538  * ->tpr_access() callback every time the guest vcpu accesses the tpr.
 539  *
 540  * \param kvm Pointer to the current kvm_context
 541  * \param vcpu vcpu to enable tpr access reporting on
 542  */
 543 int kvm_enable_tpr_access_reporting(kvm_context_t kvm, int vcpu);
 544
 545 /*!
 546  * \brief Disable kernel tpr access reporting
 547  *
 548  * Undoes the effect of kvm_enable_tpr_access_reporting().
 549  *
 550  * \param kvm Pointer to the current kvm_context
 551  * \param vcpu vcpu to disable tpr access reporting on
 552  */
 553 int kvm_disable_tpr_access_reporting(kvm_context_t kvm, int vcpu);
 554
 555 int kvm_enable_vapic(kvm_context_t kvm, int vcpu, uint64_t vapic);
 556
 557 #endif
 558
 559 #endif