kvm/user/kvmctl.h

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