xref: /illumos-gate/usr/src/uts/intel/io/vmm/sys/vmm_kernel.h (revision 29621f011bb9ea4f2d9ea887e971bbb3910ee931)
1 /*-
2  * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
3  *
4  * Copyright (c) 2011 NetApp, Inc.
5  * All rights reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  * 1. Redistributions of source code must retain the above copyright
11  *    notice, this list of conditions and the following disclaimer.
12  * 2. Redistributions in binary form must reproduce the above copyright
13  *    notice, this list of conditions and the following disclaimer in the
14  *    documentation and/or other materials provided with the distribution.
15  *
16  * THIS SOFTWARE IS PROVIDED BY NETAPP, INC ``AS IS'' AND
17  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19  * ARE DISCLAIMED.  IN NO EVENT SHALL NETAPP, INC OR CONTRIBUTORS BE LIABLE
20  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26  * SUCH DAMAGE.
27  *
28  * $FreeBSD$
29  */
30 /*
31  * This file and its contents are supplied under the terms of the
32  * Common Development and Distribution License ("CDDL"), version 1.0.
33  * You may only use this file in accordance with the terms of version
34  * 1.0 of the CDDL.
35  *
36  * A full copy of the text of the CDDL should have accompanied this
37  * source.  A copy of the CDDL is also available via the Internet at
38  * http://www.illumos.org/license/CDDL.
39  *
40  * Copyright 2015 Pluribus Networks Inc.
41  * Copyright 2019 Joyent, Inc.
42  * Copyright 2022 Oxide Computer Company
43  * Copyright 2021 OmniOS Community Edition (OmniOSce) Association.
44  */
45 
46 #ifndef _VMM_KERNEL_H_
47 #define	_VMM_KERNEL_H_
48 
49 #include <sys/sdt.h>
50 #include <x86/segments.h>
51 #include <sys/vmm.h>
52 #include <sys/vmm_data.h>
53 #include <sys/linker_set.h>
54 
55 SDT_PROVIDER_DECLARE(vmm);
56 
57 struct vm;
58 struct vm_exception;
59 struct seg_desc;
60 struct vm_exit;
61 struct vie;
62 struct vm_run;
63 struct vhpet;
64 struct vioapic;
65 struct vlapic;
66 struct vmspace;
67 struct vm_client;
68 struct vm_object;
69 struct vm_guest_paging;
70 struct vmm_data_req;
71 
72 typedef int	(*vmm_init_func_t)(void);
73 typedef int	(*vmm_cleanup_func_t)(void);
74 typedef void	(*vmm_resume_func_t)(void);
75 typedef void *	(*vmi_init_func_t)(struct vm *vm);
76 typedef int	(*vmi_run_func_t)(void *vmi, int vcpu, uint64_t rip);
77 typedef void	(*vmi_cleanup_func_t)(void *vmi);
78 typedef int	(*vmi_get_register_t)(void *vmi, int vcpu, int num,
79     uint64_t *retval);
80 typedef int	(*vmi_set_register_t)(void *vmi, int vcpu, int num,
81     uint64_t val);
82 typedef int	(*vmi_get_desc_t)(void *vmi, int vcpu, int num,
83     struct seg_desc *desc);
84 typedef int	(*vmi_set_desc_t)(void *vmi, int vcpu, int num,
85     const struct seg_desc *desc);
86 typedef int	(*vmi_get_cap_t)(void *vmi, int vcpu, int num, int *retval);
87 typedef int	(*vmi_set_cap_t)(void *vmi, int vcpu, int num, int val);
88 typedef struct vlapic *(*vmi_vlapic_init)(void *vmi, int vcpu);
89 typedef void	(*vmi_vlapic_cleanup)(void *vmi, struct vlapic *vlapic);
90 typedef void	(*vmi_savectx)(void *vmi, int vcpu);
91 typedef void	(*vmi_restorectx)(void *vmi, int vcpu);
92 
93 struct vmm_ops {
94 	vmm_init_func_t		init;		/* module wide initialization */
95 	vmm_cleanup_func_t	cleanup;
96 	vmm_resume_func_t	resume;
97 
98 	vmi_init_func_t		vminit;		/* vm-specific initialization */
99 	vmi_run_func_t		vmrun;
100 	vmi_cleanup_func_t	vmcleanup;
101 	vmi_get_register_t	vmgetreg;
102 	vmi_set_register_t	vmsetreg;
103 	vmi_get_desc_t		vmgetdesc;
104 	vmi_set_desc_t		vmsetdesc;
105 	vmi_get_cap_t		vmgetcap;
106 	vmi_set_cap_t		vmsetcap;
107 	vmi_vlapic_init		vlapic_init;
108 	vmi_vlapic_cleanup	vlapic_cleanup;
109 
110 	vmi_savectx		vmsavectx;
111 	vmi_restorectx		vmrestorectx;
112 };
113 
114 extern struct vmm_ops vmm_ops_intel;
115 extern struct vmm_ops vmm_ops_amd;
116 
117 int vm_create(uint64_t flags, struct vm **retvm);
118 void vm_destroy(struct vm *vm);
119 int vm_reinit(struct vm *vm, uint64_t);
120 uint16_t vm_get_maxcpus(struct vm *vm);
121 void vm_get_topology(struct vm *vm, uint16_t *sockets, uint16_t *cores,
122     uint16_t *threads, uint16_t *maxcpus);
123 int vm_set_topology(struct vm *vm, uint16_t sockets, uint16_t cores,
124     uint16_t threads, uint16_t maxcpus);
125 
126 /*
127  * APIs that race against hardware.
128  */
129 void vm_track_dirty_pages(struct vm *, uint64_t, size_t, uint8_t *);
130 
131 /*
132  * APIs that modify the guest memory map require all vcpus to be frozen.
133  */
134 int vm_mmap_memseg(struct vm *vm, vm_paddr_t gpa, int segid, vm_ooffset_t off,
135     size_t len, int prot, int flags);
136 int vm_munmap_memseg(struct vm *vm, vm_paddr_t gpa, size_t len);
137 int vm_alloc_memseg(struct vm *vm, int ident, size_t len, bool sysmem);
138 void vm_free_memseg(struct vm *vm, int ident);
139 int vm_map_mmio(struct vm *vm, vm_paddr_t gpa, size_t len, vm_paddr_t hpa);
140 int vm_unmap_mmio(struct vm *vm, vm_paddr_t gpa, size_t len);
141 int vm_assign_pptdev(struct vm *vm, int pptfd);
142 int vm_unassign_pptdev(struct vm *vm, int pptfd);
143 
144 /*
145  * APIs that inspect the guest memory map require only a *single* vcpu to
146  * be frozen. This acts like a read lock on the guest memory map since any
147  * modification requires *all* vcpus to be frozen.
148  */
149 int vm_mmap_getnext(struct vm *vm, vm_paddr_t *gpa, int *segid,
150     vm_ooffset_t *segoff, size_t *len, int *prot, int *flags);
151 int vm_get_memseg(struct vm *vm, int ident, size_t *len, bool *sysmem,
152     struct vm_object **objptr);
153 vm_paddr_t vmm_sysmem_maxaddr(struct vm *vm);
154 bool vm_mem_allocated(struct vm *vm, int vcpuid, vm_paddr_t gpa);
155 
156 int vm_get_register(struct vm *vm, int vcpu, int reg, uint64_t *retval);
157 int vm_set_register(struct vm *vm, int vcpu, int reg, uint64_t val);
158 int vm_get_seg_desc(struct vm *vm, int vcpu, int reg,
159     struct seg_desc *ret_desc);
160 int vm_set_seg_desc(struct vm *vm, int vcpu, int reg,
161     const struct seg_desc *desc);
162 int vm_get_run_state(struct vm *vm, int vcpuid, uint32_t *state,
163     uint8_t *sipi_vec);
164 int vm_set_run_state(struct vm *vm, int vcpuid, uint32_t state,
165     uint8_t sipi_vec);
166 int vm_get_fpu(struct vm *vm, int vcpuid, void *buf, size_t len);
167 int vm_set_fpu(struct vm *vm, int vcpuid, void *buf, size_t len);
168 int vm_run(struct vm *vm, int vcpuid, const struct vm_entry *);
169 int vm_suspend(struct vm *vm, enum vm_suspend_how how);
170 int vm_inject_nmi(struct vm *vm, int vcpu);
171 bool vm_nmi_pending(struct vm *vm, int vcpuid);
172 void vm_nmi_clear(struct vm *vm, int vcpuid);
173 int vm_inject_extint(struct vm *vm, int vcpu);
174 bool vm_extint_pending(struct vm *vm, int vcpuid);
175 void vm_extint_clear(struct vm *vm, int vcpuid);
176 int vm_inject_init(struct vm *vm, int vcpuid);
177 int vm_inject_sipi(struct vm *vm, int vcpuid, uint8_t vec);
178 struct vlapic *vm_lapic(struct vm *vm, int cpu);
179 struct vioapic *vm_ioapic(struct vm *vm);
180 struct vhpet *vm_hpet(struct vm *vm);
181 int vm_get_capability(struct vm *vm, int vcpu, int type, int *val);
182 int vm_set_capability(struct vm *vm, int vcpu, int type, int val);
183 int vm_get_x2apic_state(struct vm *vm, int vcpu, enum x2apic_state *state);
184 int vm_set_x2apic_state(struct vm *vm, int vcpu, enum x2apic_state state);
185 int vm_apicid2vcpuid(struct vm *vm, int apicid);
186 int vm_activate_cpu(struct vm *vm, int vcpu);
187 int vm_suspend_cpu(struct vm *vm, int vcpu);
188 int vm_resume_cpu(struct vm *vm, int vcpu);
189 struct vm_exit *vm_exitinfo(struct vm *vm, int vcpuid);
190 struct vie *vm_vie_ctx(struct vm *vm, int vcpuid);
191 void vm_exit_suspended(struct vm *vm, int vcpuid, uint64_t rip);
192 void vm_exit_debug(struct vm *vm, int vcpuid, uint64_t rip);
193 void vm_exit_astpending(struct vm *vm, int vcpuid, uint64_t rip);
194 void vm_exit_reqidle(struct vm *vm, int vcpuid, uint64_t rip);
195 void vm_exit_run_state(struct vm *vm, int vcpuid, uint64_t rip);
196 int vm_service_mmio_read(struct vm *vm, int cpuid, uint64_t gpa, uint64_t *rval,
197     int rsize);
198 int vm_service_mmio_write(struct vm *vm, int cpuid, uint64_t gpa, uint64_t wval,
199     int wsize);
200 
201 #ifdef _SYS__CPUSET_H_
202 cpuset_t vm_active_cpus(struct vm *vm);
203 cpuset_t vm_debug_cpus(struct vm *vm);
204 cpuset_t vm_suspended_cpus(struct vm *vm);
205 #endif	/* _SYS__CPUSET_H_ */
206 
207 bool vcpu_entry_bailout_checks(struct vm *vm, int vcpuid, uint64_t rip);
208 bool vcpu_run_state_pending(struct vm *vm, int vcpuid);
209 int vcpu_arch_reset(struct vm *vm, int vcpuid, bool init_only);
210 
211 /*
212  * Return true if device indicated by bus/slot/func is supposed to be a
213  * pci passthrough device.
214  *
215  * Return false otherwise.
216  */
217 bool vmm_is_pptdev(int bus, int slot, int func);
218 
219 void *vm_iommu_domain(struct vm *vm);
220 
221 enum vcpu_state {
222 	VCPU_IDLE,
223 	VCPU_FROZEN,
224 	VCPU_RUNNING,
225 	VCPU_SLEEPING,
226 };
227 
228 int vcpu_set_state(struct vm *vm, int vcpu, enum vcpu_state state,
229     bool from_idle);
230 enum vcpu_state vcpu_get_state(struct vm *vm, int vcpu, int *hostcpu);
231 void vcpu_block_run(struct vm *, int);
232 void vcpu_unblock_run(struct vm *, int);
233 
234 uint64_t vcpu_tsc_offset(struct vm *vm, int vcpuid, bool phys_adj);
235 hrtime_t vm_normalize_hrtime(struct vm *, hrtime_t);
236 hrtime_t vm_denormalize_hrtime(struct vm *, hrtime_t);
237 
238 static __inline bool
239 vcpu_is_running(struct vm *vm, int vcpu, int *hostcpu)
240 {
241 	return (vcpu_get_state(vm, vcpu, hostcpu) == VCPU_RUNNING);
242 }
243 
244 #ifdef _SYS_THREAD_H
245 static __inline int
246 vcpu_should_yield(struct vm *vm, int vcpu)
247 {
248 
249 	if (curthread->t_astflag)
250 		return (1);
251 	else if (CPU->cpu_runrun)
252 		return (1);
253 	else
254 		return (0);
255 }
256 #endif /* _SYS_THREAD_H */
257 
258 typedef enum vcpu_notify {
259 	VCPU_NOTIFY_NONE,
260 	VCPU_NOTIFY_APIC,	/* Posted intr notification (if possible) */
261 	VCPU_NOTIFY_EXIT,	/* IPI to cause VM exit */
262 } vcpu_notify_t;
263 
264 void *vcpu_stats(struct vm *vm, int vcpu);
265 void vcpu_notify_event(struct vm *vm, int vcpuid);
266 void vcpu_notify_event_type(struct vm *vm, int vcpuid, vcpu_notify_t);
267 struct vmspace *vm_get_vmspace(struct vm *vm);
268 struct vm_client *vm_get_vmclient(struct vm *vm, int vcpuid);
269 struct vatpic *vm_atpic(struct vm *vm);
270 struct vatpit *vm_atpit(struct vm *vm);
271 struct vpmtmr *vm_pmtmr(struct vm *vm);
272 struct vrtc *vm_rtc(struct vm *vm);
273 
274 /*
275  * Inject exception 'vector' into the guest vcpu. This function returns 0 on
276  * success and non-zero on failure.
277  *
278  * Wrapper functions like 'vm_inject_gp()' should be preferred to calling
279  * this function directly because they enforce the trap-like or fault-like
280  * behavior of an exception.
281  *
282  * This function should only be called in the context of the thread that is
283  * executing this vcpu.
284  */
285 int vm_inject_exception(struct vm *vm, int vcpuid, uint8_t vector,
286     bool err_valid, uint32_t errcode, bool restart_instruction);
287 
288 /*
289  * This function is called after a VM-exit that occurred during exception or
290  * interrupt delivery through the IDT. The format of 'intinfo' is described
291  * in Figure 15-1, "EXITINTINFO for All Intercepts", APM, Vol 2.
292  *
293  * If a VM-exit handler completes the event delivery successfully then it
294  * should call vm_exit_intinfo() to extinguish the pending event. For e.g.,
295  * if the task switch emulation is triggered via a task gate then it should
296  * call this function with 'intinfo=0' to indicate that the external event
297  * is not pending anymore.
298  *
299  * Return value is 0 on success and non-zero on failure.
300  */
301 int vm_exit_intinfo(struct vm *vm, int vcpuid, uint64_t intinfo);
302 
303 /*
304  * This function is called before every VM-entry to retrieve a pending
305  * event that should be injected into the guest. This function combines
306  * nested events into a double or triple fault.
307  *
308  * Returns false if there are no events that need to be injected into the guest.
309  */
310 bool vm_entry_intinfo(struct vm *vm, int vcpuid, uint64_t *info);
311 
312 int vm_get_intinfo(struct vm *vm, int vcpuid, uint64_t *info1, uint64_t *info2);
313 
314 enum vm_reg_name vm_segment_name(int seg_encoding);
315 
316 struct vm_copyinfo {
317 	uint64_t	gpa;
318 	size_t		len;
319 	int		prot;
320 	void		*hva;
321 	void		*cookie;
322 };
323 
324 /*
325  * Set up 'copyinfo[]' to copy to/from guest linear address space starting
326  * at 'gla' and 'len' bytes long. The 'prot' should be set to PROT_READ for
327  * a copyin or PROT_WRITE for a copyout.
328  *
329  * retval	is_fault	Interpretation
330  *   0		   0		Success
331  *   0		   1		An exception was injected into the guest
332  * EFAULT	  N/A		Unrecoverable error
333  *
334  * The 'copyinfo[]' can be passed to 'vm_copyin()' or 'vm_copyout()' only if
335  * the return value is 0. The 'copyinfo[]' resources should be freed by calling
336  * 'vm_copy_teardown()' after the copy is done.
337  */
338 int vm_copy_setup(struct vm *vm, int vcpuid, struct vm_guest_paging *paging,
339     uint64_t gla, size_t len, int prot, struct vm_copyinfo *copyinfo,
340     uint_t num_copyinfo, int *is_fault);
341 void vm_copy_teardown(struct vm *vm, int vcpuid, struct vm_copyinfo *copyinfo,
342     uint_t num_copyinfo);
343 void vm_copyin(struct vm *vm, int vcpuid, struct vm_copyinfo *copyinfo,
344     void *kaddr, size_t len);
345 void vm_copyout(struct vm *vm, int vcpuid, const void *kaddr,
346     struct vm_copyinfo *copyinfo, size_t len);
347 
348 int vcpu_trace_exceptions(struct vm *vm, int vcpuid);
349 
350 void vm_inject_ud(struct vm *vm, int vcpuid);
351 void vm_inject_gp(struct vm *vm, int vcpuid);
352 void vm_inject_ac(struct vm *vm, int vcpuid, uint32_t errcode);
353 void vm_inject_ss(struct vm *vm, int vcpuid, uint32_t errcode);
354 void vm_inject_pf(struct vm *vm, int vcpuid, uint32_t errcode, uint64_t cr2);
355 
356 /*
357  * Both SVM and VMX have complex logic for injecting events such as exceptions
358  * or interrupts into the guest.  Within those two backends, the progress of
359  * event injection is tracked by event_inject_state, hopefully making it easier
360  * to reason about.
361  */
362 enum event_inject_state {
363 	EIS_CAN_INJECT	= 0, /* exception/interrupt can be injected */
364 	EIS_EV_EXISTING	= 1, /* blocked by existing event */
365 	EIS_EV_INJECTED	= 2, /* blocked by injected event */
366 	EIS_GI_BLOCK	= 3, /* blocked by guest interruptability */
367 
368 	/*
369 	 * Flag to request an immediate exit from VM context after event
370 	 * injection in order to perform more processing
371 	 */
372 	EIS_REQ_EXIT	= (1 << 15),
373 };
374 
375 /* Possible result codes for MSR access emulation */
376 typedef enum vm_msr_result {
377 	VMR_OK		= 0, /* succesfully emulated */
378 	VMR_GP		= 1, /* #GP should be injected */
379 	VMR_UNHANLDED	= 2, /* handle in userspace, kernel cannot emulate */
380 } vm_msr_result_t;
381 
382 void vmm_sol_glue_init(void);
383 void vmm_sol_glue_cleanup(void);
384 
385 void *vmm_contig_alloc(size_t);
386 void vmm_contig_free(void *, size_t);
387 
388 int vmm_mod_load(void);
389 int vmm_mod_unload(void);
390 
391 bool vmm_check_iommu(void);
392 
393 void vmm_call_trap(uint64_t);
394 
395 /*
396  * Because of tangled headers, this is not exposed directly via the vmm_drv
397  * interface, but rather mirrored as vmm_drv_iop_cb_t in vmm_drv.h.
398  */
399 typedef int (*ioport_handler_t)(void *, bool, uint16_t, uint8_t, uint32_t *);
400 
401 int vm_ioport_access(struct vm *vm, int vcpuid, bool in, uint16_t port,
402     uint8_t bytes, uint32_t *val);
403 
404 int vm_ioport_attach(struct vm *vm, uint16_t port, ioport_handler_t func,
405     void *arg, void **cookie);
406 int vm_ioport_detach(struct vm *vm, void **cookie, ioport_handler_t *old_func,
407     void **old_arg);
408 
409 int vm_ioport_hook(struct vm *, uint16_t, ioport_handler_t, void *, void **);
410 void vm_ioport_unhook(struct vm *, void **);
411 
412 enum vcpu_ustate {
413 	VU_INIT = 0,	/* initialized but has not yet attempted to run */
414 	VU_RUN,		/* running in guest context */
415 	VU_IDLE,	/* idle (HLTed, wait-for-SIPI, etc) */
416 	VU_EMU_KERN,	/* emulation performed in-kernel */
417 	VU_EMU_USER,	/* emulation performed in userspace */
418 	VU_SCHED,	/* off-cpu for interrupt, preempt, lock contention */
419 	VU_MAX
420 };
421 
422 void vcpu_ustate_change(struct vm *, int, enum vcpu_ustate);
423 
424 typedef struct vmm_kstats {
425 	kstat_named_t	vk_name;
426 } vmm_kstats_t;
427 
428 typedef struct vmm_vcpu_kstats {
429 	kstat_named_t	vvk_vcpu;
430 	kstat_named_t	vvk_time_init;
431 	kstat_named_t	vvk_time_run;
432 	kstat_named_t	vvk_time_idle;
433 	kstat_named_t	vvk_time_emu_kern;
434 	kstat_named_t	vvk_time_emu_user;
435 	kstat_named_t	vvk_time_sched;
436 } vmm_vcpu_kstats_t;
437 
438 #define	VMM_KSTAT_CLASS	"misc"
439 
440 int vmm_kstat_update_vcpu(struct kstat *, int);
441 
442 typedef struct vmm_data_req {
443 	uint16_t	vdr_class;
444 	uint16_t	vdr_version;
445 	uint32_t	vdr_flags;
446 	uint32_t	vdr_len;
447 	void		*vdr_data;
448 } vmm_data_req_t;
449 typedef struct vmm_data_req vmm_data_req_t;
450 
451 typedef int (*vmm_data_writef_t)(void *, const vmm_data_req_t *);
452 typedef int (*vmm_data_readf_t)(void *, const vmm_data_req_t *);
453 
454 typedef struct vmm_data_version_entry {
455 	uint16_t		vdve_class;
456 	uint16_t		vdve_version;
457 	uint16_t		vdve_len_expect;
458 	vmm_data_readf_t	vdve_readf;
459 	vmm_data_writef_t	vdve_writef;
460 } vmm_data_version_entry_t;
461 
462 #define	VMM_DATA_VERSION(sym)	SET_ENTRY(vmm_data_version_entries, sym)
463 
464 int vmm_data_read(struct vm *, int, const vmm_data_req_t *);
465 int vmm_data_write(struct vm *, int, const vmm_data_req_t *);
466 
467 #endif /* _VMM_KERNEL_H_ */
468