1/* SPDX-License-Identifier: GPL-2.0-or-later */
2/*
3 * Copyright (C) 2021 SUSE LLC <mdoucha@suse.cz>
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
50struct 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 */
59extern const char kvm_payload_start[], kvm_payload_end[];
60
61/* CPU reset code to be installed into the VM at VM_RESET_BASEADDR */
62extern const unsigned char tst_kvm_reset_code[VM_RESET_CODE_SIZE];
63
64/* Default KVM test functions. */
65void tst_kvm_setup(void);
66void tst_kvm_run(void);
67void 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 */
74void 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 */
86void *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 */
93uint64_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 */
101int tst_kvm_find_phys_memslot(const struct tst_kvm_instance *inst,
102	uint64_t paddr);
103int 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 */
108void *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 */
117struct 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 */
125void 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 */
132int tst_kvm_run_instance(struct tst_kvm_instance *inst, int exp_errno);
133
134/*
135 * Close the given KVM instance.
136 */
137void 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 */
145int 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 */
151void tst_kvm_clear_guest_signal(struct tst_kvm_instance *inst);
152
153#endif /* KVM_HOST_H_ */
154