1 /* SPDX-License-Identifier: GPL-2.0-or-later */ 2 /* 3 * Copyright (C) 2021 SUSE LLC <[email protected]> 4 * 5 * KVM host library for setting up and running virtual machine tests. Tests 6 * can either use the default setup/run/host functions or use the advanced 7 * API to create customized VMs. 8 */ 9 10 /* 11 * Most basic usage: 12 * 13 * #include "kvm_test.h" 14 * 15 * #ifdef COMPILE_PAYLOAD 16 * 17 * void main(void) 18 * { 19 * [VM guest code goes here] 20 * } 21 * 22 * #else 23 * 24 * [optional VM host setup/run/cleanup code goes here] 25 * 26 * static struct tst_test test = { 27 * .test_all = tst_kvm_run, 28 * .setup = tst_kvm_setup, 29 * .cleanup = tst_kvm_cleanup, 30 * }; 31 * 32 * #endif 33 */ 34 35 #ifndef KVM_HOST_H_ 36 #define KVM_HOST_H_ 37 38 #include <inttypes.h> 39 #include <linux/kvm.h> 40 #include "kvm_common.h" 41 42 #define VM_KERNEL_BASEADDR 0x1000 43 #define VM_RESET_BASEADDR 0xfffffff0 44 #define VM_RESET_CODE_SIZE 8 45 46 #define MIN_FREE_RAM (10 * 1024 * 1024) 47 #define DEFAULT_RAM_SIZE (16 * 1024 * 1024) 48 #define MAX_KVM_MEMSLOTS 8 49 50 struct tst_kvm_instance { 51 int vm_fd, vcpu_fd; 52 struct kvm_run *vcpu_info; 53 size_t vcpu_info_size; 54 struct kvm_userspace_memory_region ram[MAX_KVM_MEMSLOTS]; 55 struct tst_kvm_result *result; 56 }; 57 58 /* Test binary to be installed into the VM at VM_KERNEL_BASEADDR */ 59 extern const char kvm_payload_start[], kvm_payload_end[]; 60 61 /* CPU reset code to be installed into the VM at VM_RESET_BASEADDR */ 62 extern const unsigned char tst_kvm_reset_code[VM_RESET_CODE_SIZE]; 63 64 /* Default KVM test functions. */ 65 void tst_kvm_setup(void); 66 void tst_kvm_run(void); 67 void tst_kvm_cleanup(void); 68 69 /* 70 * Validate KVM guest test result (usually passed via result->result) and 71 * fail with TBROK if the value cannot be safely passed to tst_res() or 72 * tst_brk(). 73 */ 74 void tst_kvm_validate_result(int value); 75 76 /* 77 * Allocate memory slot for the VM. The returned pointer is page-aligned 78 * so the actual requested base address is at ret[baseaddr % pagesize]. 79 * 80 * The first argument is a VM file descriptor created by ioctl(KVM_CREATE_VM) 81 * 82 * The return value points to a guarded buffer and the user should not attempt 83 * to free() it. Any extra space added at the beginning or end for page 84 * alignment will be writable. 85 */ 86 void *tst_kvm_alloc_memory(struct tst_kvm_instance *inst, unsigned int slot, 87 uint64_t baseaddr, size_t size, unsigned int flags); 88 89 /* 90 * Translate VM virtual memory address to the corresponding physical address. 91 * Returns 0 if the virtual address is unmapped or otherwise invalid. 92 */ 93 uint64_t tst_kvm_get_phys_address(const struct tst_kvm_instance *inst, 94 uint64_t addr); 95 96 /* 97 * Find the struct tst_kvm_instance memory slot ID for the give virtual 98 * or physical VM memory address. Returns -1 if the address is not backed 99 * by any memory buffer. 100 */ 101 int tst_kvm_find_phys_memslot(const struct tst_kvm_instance *inst, 102 uint64_t paddr); 103 int tst_kvm_find_memslot(const struct tst_kvm_instance *inst, uint64_t addr); 104 105 /* 106 * Convert VM virtual memory address to a directly usable pointer. 107 */ 108 void *tst_kvm_get_memptr(const struct tst_kvm_instance *inst, uint64_t addr); 109 110 /* 111 * Find CPUIDs supported by KVM. x86_64 tests must set non-default CPUID, 112 * otherwise bootstrap will fail to initialize 64bit mode. 113 * Returns NULL if ioctl(KVM_GET_SUPPORTED_CPUID) is not supported. 114 * 115 * The argument is a file descriptor created by open("/dev/kvm") 116 */ 117 struct kvm_cpuid2 *tst_kvm_get_cpuid(int sysfd); 118 119 /* 120 * Initialize the given KVM instance structure. Creates new KVM virtual machine 121 * with 1 virtual CPU, allocates VM RAM (max. 4GB minus one page) and 122 * shared result structure. KVM memory slots 0 and 1 will be set by this 123 * function. 124 */ 125 void tst_kvm_create_instance(struct tst_kvm_instance *inst, size_t ram_size); 126 127 /* 128 * Execute the given KVM instance and print results. If ioctl(KVM_RUN) is 129 * expected to fail, pass the expected error code in exp_errno, otherwise 130 * set it to zero. Returns last value returned by ioctl(KVM_RUN). 131 */ 132 int tst_kvm_run_instance(struct tst_kvm_instance *inst, int exp_errno); 133 134 /* 135 * Close the given KVM instance. 136 */ 137 void tst_kvm_destroy_instance(struct tst_kvm_instance *inst); 138 139 /* 140 * Wait for given VM to call tst_signal_host() or tst_wait_host(). Timeout 141 * value is in milliseconds. Zero means no wait, negative value means wait 142 * forever. Returns 0 if signal was received, KVM_TEXIT if the VM exited 143 * without sending a signal, or -1 if timeout was reached. 144 */ 145 int tst_kvm_wait_guest(struct tst_kvm_instance *inst, int timeout_ms); 146 147 /* 148 * Clear VM signal sent by tst_signal_host(). If the VM is waiting 149 * in tst_wait_host(), this function will signal the VM to resume execution. 150 */ 151 void tst_kvm_clear_guest_signal(struct tst_kvm_instance *inst); 152 153 #endif /* KVM_HOST_H_ */ 154