kvm: libkvm: Add libkvm interface to get/set the mpstate.
[qemu-kvm/fedora.git] / kvm / libkvm / libkvm.h
blob5a522e30b42e6c4100dc7bc5f935812ac2ea10dd
1 /** \file libkvm.h
2 * libkvm API
3 */
5 #ifndef LIBKVM_H
6 #define LIBKVM_H
8 #include <stdint.h>
10 #ifndef __user
11 #define __user /* temporary, until installed via make headers_install */
12 #endif
14 #include <linux/kvm.h>
16 #include <signal.h>
18 struct kvm_context;
20 typedef struct kvm_context *kvm_context_t;
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
28 /*!
29 * \brief KVM callbacks structure
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.
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.
58 * Typically, you should yeild here to prevent 100% CPU utilization
59 * on the host CPU.
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)(int vcpu, uint32_t dcrn, uint32_t *data);
70 int (*powerpc_dcr_write)(int vcpu, uint32_t dcrn, uint32_t data);
71 #endif
74 /*!
75 * \brief Create new KVM context
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.
81 * \param callbacks Pointer to a valid kvm_callbacks structure
82 * \param opaque Not used
83 * \return NULL on failure
85 kvm_context_t kvm_init(struct kvm_callbacks *callbacks,
86 void *opaque);
88 /*!
89 * \brief Cleanup the KVM context
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
95 * \param kvm Pointer to the kvm_context that is to be freed
97 void kvm_finalize(kvm_context_t kvm);
99 /*!
100 * \brief Disable the in-kernel IRQCHIP creation
102 * In-kernel irqchip is enabled by default. If userspace irqchip is to be used,
103 * this should be called prior to kvm_create().
105 * \param kvm Pointer to the kvm_context
107 void kvm_disable_irqchip_creation(kvm_context_t kvm);
110 * \brief Disable the in-kernel PIT creation
112 * In-kernel pit is enabled by default. If userspace pit is to be used,
113 * this should be called prior to kvm_create().
115 * \param kvm Pointer to the kvm_context
117 void kvm_disable_pit_creation(kvm_context_t kvm);
120 * \brief Create new virtual machine
122 * This creates a new virtual machine, maps physical RAM to it, and creates a
123 * virtual CPU for it.\n
124 * \n
125 * Memory gets mapped for addresses 0->0xA0000, 0xC0000->phys_mem_bytes
127 * \param kvm Pointer to the current kvm_context
128 * \param phys_mem_bytes The amount of physical ram you want the VM to have
129 * \param phys_mem This pointer will be set to point to the memory that
130 * kvm_create allocates for physical RAM
131 * \return 0 on success
133 int kvm_create(kvm_context_t kvm,
134 unsigned long phys_mem_bytes,
135 void **phys_mem);
136 int kvm_create_vm(kvm_context_t kvm);
137 int kvm_check_extension(kvm_context_t kvm, int ext);
138 void kvm_create_irqchip(kvm_context_t kvm);
141 * \brief Create a new virtual cpu
143 * This creates a new virtual cpu (the first vcpu is created by kvm_create()).
144 * Should be called from a thread dedicated to the vcpu.
146 * \param kvm kvm context
147 * \param slot vcpu number (> 0)
148 * \return 0 on success, -errno on failure
150 int kvm_create_vcpu(kvm_context_t kvm, int slot);
153 * \brief Start the VCPU
155 * This starts the VCPU and virtualization is started.\n
156 * \n
157 * This function will not return until any of these conditions are met:
158 * - An IO/MMIO handler does not return "0"
159 * - An exception that neither the guest OS, nor KVM can handle occurs
161 * \note This function will call the callbacks registered in kvm_init()
162 * to emulate those functions
163 * \note If you at any point want to interrupt the VCPU, kvm_run() will
164 * listen to the EINTR signal. This allows you to simulate external interrupts
165 * and asyncronous IO.
167 * \param kvm Pointer to the current kvm_context
168 * \param vcpu Which virtual CPU should be started
169 * \return 0 on success, but you really shouldn't expect this function to
170 * return except for when an error has occured, or when you have sent it
171 * an EINTR signal.
173 int kvm_run(kvm_context_t kvm, int vcpu);
176 * \brief Get interrupt flag from on last exit to userspace
178 * This gets the CPU interrupt flag as it was on the last exit to userspace.
180 * \param kvm Pointer to the current kvm_context
181 * \param vcpu Which virtual CPU should get dumped
182 * \return interrupt flag value (0 or 1)
184 int kvm_get_interrupt_flag(kvm_context_t kvm, int vcpu);
187 * \brief Get the value of the APIC_BASE msr as of last exit to userspace
189 * This gets the APIC_BASE msr as it was on the last exit to userspace.
191 * \param kvm Pointer to the current kvm_context
192 * \param vcpu Which virtual CPU should get dumped
193 * \return APIC_BASE msr contents
195 uint64_t kvm_get_apic_base(kvm_context_t kvm, int vcpu);
198 * \brief Check if a vcpu is ready for interrupt injection
200 * This checks if vcpu interrupts are not masked by mov ss or sti.
202 * \param kvm Pointer to the current kvm_context
203 * \param vcpu Which virtual CPU should get dumped
204 * \return boolean indicating interrupt injection readiness
206 int kvm_is_ready_for_interrupt_injection(kvm_context_t kvm, int vcpu);
209 * \brief Read VCPU registers
211 * This gets the GP registers from the VCPU and outputs them
212 * into a kvm_regs structure
214 * \note This function returns a \b copy of the VCPUs registers.\n
215 * If you wish to modify the VCPUs GP registers, you should call kvm_set_regs()
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
223 int kvm_get_regs(kvm_context_t kvm, int vcpu, struct kvm_regs *regs);
226 * \brief Write VCPU registers
228 * This sets the GP registers on the VCPU from a kvm_regs structure
230 * \note When this function returns, the regs pointer and the data it points to
231 * can be discarded
232 * \param kvm Pointer to the current kvm_context
233 * \param vcpu Which virtual CPU should get dumped
234 * \param regs Pointer to a kvm_regs which will be populated with the VCPUs
235 * registers values
236 * \return 0 on success
238 int kvm_set_regs(kvm_context_t kvm, int vcpu, struct kvm_regs *regs);
240 * \brief Read VCPU fpu registers
242 * This gets the FPU registers from the VCPU and outputs them
243 * into a kvm_fpu structure
245 * \note This function returns a \b copy of the VCPUs registers.\n
246 * If you wish to modify the VCPU FPU registers, you should call kvm_set_fpu()
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 will be populated with the VCPUs
251 * fpu registers values
252 * \return 0 on success
254 int kvm_get_fpu(kvm_context_t kvm, int vcpu, struct kvm_fpu *fpu);
257 * \brief Write VCPU fpu registers
259 * This sets the FPU registers on the VCPU from a kvm_fpu structure
261 * \note When this function returns, the fpu pointer and the data it points to
262 * can be discarded
263 * \param kvm Pointer to the current kvm_context
264 * \param vcpu Which virtual CPU should get dumped
265 * \param fpu Pointer to a kvm_fpu which holds the new vcpu fpu state
266 * \return 0 on success
268 int kvm_set_fpu(kvm_context_t kvm, int vcpu, struct kvm_fpu *fpu);
271 * \brief Read VCPU system registers
273 * This gets the non-GP registers from the VCPU and outputs them
274 * into a kvm_sregs structure
276 * \note This function returns a \b copy of the VCPUs registers.\n
277 * If you wish to modify the VCPUs non-GP registers, you should call
278 * kvm_set_sregs()
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
286 int kvm_get_sregs(kvm_context_t kvm, int vcpu, struct kvm_sregs *regs);
289 * \brief Write VCPU system registers
291 * This sets the non-GP registers on the VCPU from a kvm_sregs structure
293 * \note When this function returns, the regs pointer and the data it points to
294 * can be discarded
295 * \param kvm Pointer to the current kvm_context
296 * \param vcpu Which virtual CPU should get dumped
297 * \param regs Pointer to a kvm_sregs which will be populated with the VCPUs
298 * registers values
299 * \return 0 on success
301 int kvm_set_sregs(kvm_context_t kvm, int vcpu, struct kvm_sregs *regs);
303 #ifdef KVM_CAP_MP_STATE
305 * * \brief Read VCPU MP state
308 int kvm_get_mpstate(kvm_context_t kvm, int vcpu,
309 struct kvm_mp_state *mp_state);
312 * * \brief Write VCPU MP state
315 int kvm_set_mpstate(kvm_context_t kvm, int vcpu,
316 struct kvm_mp_state *mp_state);
317 #endif
320 * \brief Simulate an external vectored interrupt
322 * This allows you to simulate an external vectored interrupt.
324 * \param kvm Pointer to the current kvm_context
325 * \param vcpu Which virtual CPU should get dumped
326 * \param irq Vector number
327 * \return 0 on success
329 int kvm_inject_irq(kvm_context_t kvm, int vcpu, unsigned irq);
331 int kvm_guest_debug(kvm_context_t, int vcpu, struct kvm_debug_guest *dbg);
333 #if defined(__i386__) || defined(__x86_64__)
335 * \brief Setup a vcpu's cpuid instruction emulation
337 * Set up a table of cpuid function to cpuid outputs.\n
339 * \param kvm Pointer to the current kvm_context
340 * \param vcpu Which virtual CPU should be initialized
341 * \param nent number of entries to be installed
342 * \param entries cpuid function entries table
343 * \return 0 on success, or -errno on error
345 int kvm_setup_cpuid(kvm_context_t kvm, int vcpu, int nent,
346 struct kvm_cpuid_entry *entries);
349 * \brief Setting the number of shadow pages to be allocated to the vm
351 * \param kvm pointer to kvm_context
352 * \param nrshadow_pages number of pages to be allocated
354 int kvm_set_shadow_pages(kvm_context_t kvm, unsigned int nrshadow_pages);
357 * \breif Getting the number of shadow pages that are allocated to the vm
359 * \param kvm pointer to kvm_context
360 * \param nrshadow_pages number of pages to be allocated
362 int kvm_get_shadow_pages(kvm_context_t kvm , unsigned int *nrshadow_pages);
365 * \brief Set up cr8 for next time the vcpu is executed
367 * This is a fast setter for cr8, which will be applied when the
368 * vcpu next enters guest mode.
370 * \param kvm Pointer to the current kvm_context
371 * \param vcpu Which virtual CPU should get dumped
372 * \param cr8 next cr8 value
374 void kvm_set_cr8(kvm_context_t kvm, int vcpu, uint64_t cr8);
377 * \brief Get cr8 for sync tpr in qemu apic emulation
379 * This is a getter for cr8, which used to sync with the tpr in qemu
380 * apic emualtion.
382 * \param kvm Pointer to the current kvm_context
383 * \param vcpu Which virtual CPU should get dumped
385 __u64 kvm_get_cr8(kvm_context_t kvm, int vcpu);
386 #endif
389 * \brief Set a vcpu's signal mask for guest mode
391 * A vcpu can have different signals blocked in guest mode and user mode.
392 * This allows guest execution to be interrupted on a signal, without requiring
393 * that the signal be delivered to a signal handler (the signal can be
394 * dequeued using sigwait(2).
396 * \param kvm Pointer to the current kvm_context
397 * \param vcpu Which virtual CPU should be initialized
398 * \param sigset signal mask for guest mode
399 * \return 0 on success, or -errno on error
401 int kvm_set_signal_mask(kvm_context_t kvm, int vcpu, const sigset_t *sigset);
404 * \brief Dump all VCPU information
406 * This dumps \b all the information that KVM has about a virtual CPU, namely:
407 * - GP Registers
408 * - System registers (selectors, descriptors, etc)
409 * - VMCS Data
410 * - MSRS
411 * - Pending interrupts
413 * \param kvm Pointer to the current kvm_context
414 * \param vcpu Which virtual CPU should get dumped
415 * \return 0 on success
417 int kvm_dump_vcpu(kvm_context_t kvm, int vcpu);
420 * \brief Dump VCPU registers
422 * This dumps some of the information that KVM has about a virtual CPU, namely:
423 * - GP Registers
425 * A much more verbose version of this is available as kvm_dump_vcpu()
427 * \param kvm Pointer to the current kvm_context
428 * \param vcpu Which virtual CPU should get dumped
429 * \return 0 on success
431 void kvm_show_regs(kvm_context_t kvm, int vcpu);
434 void *kvm_create_phys_mem(kvm_context_t, unsigned long phys_start,
435 unsigned long len, int log, int writable);
436 void kvm_destroy_phys_mem(kvm_context_t, unsigned long phys_start,
437 unsigned long len);
438 int kvm_is_intersecting_mem(kvm_context_t kvm, unsigned long phys_start);
439 int kvm_is_allocated_mem(kvm_context_t kvm, unsigned long phys_start,
440 unsigned long len);
441 int kvm_create_mem_hole(kvm_context_t kvm, unsigned long phys_start,
442 unsigned long len);
443 int kvm_register_userspace_phys_mem(kvm_context_t kvm,
444 unsigned long phys_start, void *userspace_addr,
445 unsigned long len, int log);
446 int kvm_get_dirty_pages(kvm_context_t, unsigned long phys_addr, void *buf);
447 int kvm_get_dirty_pages_range(kvm_context_t kvm, unsigned long phys_addr,
448 unsigned long end_addr, void *buf, void*opaque,
449 int (*cb)(unsigned long start, unsigned long len,
450 void*bitmap, void *opaque));
453 * \brief Create a memory alias
455 * Aliases a portion of physical memory to another portion. If the guest
456 * accesses the alias region, it will behave exactly as if it accessed
457 * the target memory.
459 int kvm_create_memory_alias(kvm_context_t,
460 uint64_t phys_start, uint64_t len,
461 uint64_t target_phys);
464 * \brief Destroy a memory alias
466 * Removes an alias created with kvm_create_memory_alias().
468 int kvm_destroy_memory_alias(kvm_context_t, uint64_t phys_start);
471 * \brief Get a bitmap of guest ram pages which are allocated to the guest.
473 * \param kvm Pointer to the current kvm_context
474 * \param phys_addr Memory slot phys addr
475 * \param bitmap Long aligned address of a big enough bitmap (one bit per page)
477 int kvm_get_mem_map(kvm_context_t kvm, unsigned long phys_addr, void *bitmap);
478 int kvm_get_mem_map_range(kvm_context_t kvm, unsigned long phys_addr,
479 unsigned long len, void *buf, void *opaque,
480 int (*cb)(unsigned long start,unsigned long len,
481 void* bitmap, void* opaque));
482 int kvm_set_irq_level(kvm_context_t kvm, int irq, int level);
485 * \brief Enable dirty-pages-logging for all memory regions
487 * \param kvm Pointer to the current kvm_context
489 int kvm_dirty_pages_log_enable_all(kvm_context_t kvm);
492 * \brief Disable dirty-page-logging for some memory regions
494 * Disable dirty-pages-logging for those memory regions that were
495 * created with dirty-page-logging disabled.
497 * \param kvm Pointer to the current kvm_context
499 int kvm_dirty_pages_log_reset(kvm_context_t kvm);
502 * \brief Query whether in kernel irqchip is used
504 * \param kvm Pointer to the current kvm_context
506 int kvm_irqchip_in_kernel(kvm_context_t kvm);
508 #ifdef KVM_CAP_IRQCHIP
510 * \brief Dump in kernel IRQCHIP contents
512 * Dump one of the in kernel irq chip devices, including PIC (master/slave)
513 * and IOAPIC into a kvm_irqchip structure
515 * \param kvm Pointer to the current kvm_context
516 * \param chip The irq chip device to be dumped
518 int kvm_get_irqchip(kvm_context_t kvm, struct kvm_irqchip *chip);
521 * \brief Set in kernel IRQCHIP contents
523 * Write one of the in kernel irq chip devices, including PIC (master/slave)
524 * and IOAPIC
527 * \param kvm Pointer to the current kvm_context
528 * \param chip THe irq chip device to be written
530 int kvm_set_irqchip(kvm_context_t kvm, struct kvm_irqchip *chip);
532 #if defined(__i386__) || defined(__x86_64__)
534 * \brief Get in kernel local APIC for vcpu
536 * Save the local apic state including the timer of a virtual CPU
538 * \param kvm Pointer to the current kvm_context
539 * \param vcpu Which virtual CPU should be accessed
540 * \param s Local apic state of the specific virtual CPU
542 int kvm_get_lapic(kvm_context_t kvm, int vcpu, struct kvm_lapic_state *s);
545 * \brief Set in kernel local APIC for vcpu
547 * Restore the local apic state including the timer of a virtual CPU
549 * \param kvm Pointer to the current kvm_context
550 * \param vcpu Which virtual CPU should be accessed
551 * \param s Local apic state of the specific virtual CPU
553 int kvm_set_lapic(kvm_context_t kvm, int vcpu, struct kvm_lapic_state *s);
555 #endif
557 #endif
560 * \brief Query wheather in kernel pit is used
562 * \param kvm Pointer to the current kvm_context
564 int kvm_pit_in_kernel(kvm_context_t kvm);
566 #ifdef KVM_CAP_PIT
569 * \brief Get in kernel PIT of the virtual domain
571 * Save the PIT state.
573 * \param kvm Pointer to the current kvm_context
574 * \param s PIT state of the virtual domain
576 int kvm_get_pit(kvm_context_t kvm, struct kvm_pit_state *s);
579 * \brief Set in kernel PIT of the virtual domain
581 * Restore the PIT state.
582 * Timer would be retriggerred after restored.
584 * \param kvm Pointer to the current kvm_context
585 * \param s PIT state of the virtual domain
587 int kvm_set_pit(kvm_context_t kvm, struct kvm_pit_state *s);
589 #endif
591 #ifdef KVM_CAP_VAPIC
594 * \brief Enable kernel tpr access reporting
596 * When tpr access reporting is enabled, the kernel will call the
597 * ->tpr_access() callback every time the guest vcpu accesses the tpr.
599 * \param kvm Pointer to the current kvm_context
600 * \param vcpu vcpu to enable tpr access reporting on
602 int kvm_enable_tpr_access_reporting(kvm_context_t kvm, int vcpu);
605 * \brief Disable kernel tpr access reporting
607 * Undoes the effect of kvm_enable_tpr_access_reporting().
609 * \param kvm Pointer to the current kvm_context
610 * \param vcpu vcpu to disable tpr access reporting on
612 int kvm_disable_tpr_access_reporting(kvm_context_t kvm, int vcpu);
614 int kvm_enable_vapic(kvm_context_t kvm, int vcpu, uint64_t vapic);
616 #endif
618 #endif