mshv.h

  1/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
  2/*
  3 * Userspace interfaces for /dev/mshv* devices and derived fds
  4 *
  5 * This file is divided into sections containing data structures and IOCTLs for
  6 * a particular set of related devices or derived file descriptors.
  7 *
  8 * The IOCTL definitions are at the end of each section. They are grouped by
  9 * device/fd, so that new IOCTLs can easily be added with a monotonically
 10 * increasing number.
 11 */
 12#ifndef _UAPI_LINUX_MSHV_H
 13#define _UAPI_LINUX_MSHV_H
 14
 15#include <linux/types.h>
 16
 17#define MSHV_IOCTL	0xB8
 18
 19/*
 20 *******************************************
 21 * Entry point to main VMM APIs: /dev/mshv *
 22 *******************************************
 23 */
 24
 25enum {
 26	MSHV_PT_BIT_LAPIC,
 27	MSHV_PT_BIT_X2APIC,
 28	MSHV_PT_BIT_GPA_SUPER_PAGES,
 29	MSHV_PT_BIT_CPU_AND_XSAVE_FEATURES,
 30	MSHV_PT_BIT_COUNT,
 31};
 32
 33#define MSHV_PT_FLAGS_MASK ((1 << MSHV_PT_BIT_COUNT) - 1)
 34
 35enum {
 36	MSHV_PT_ISOLATION_NONE,
 37	MSHV_PT_ISOLATION_COUNT,
 38};
 39
 40/**
 41 * struct mshv_create_partition - arguments for MSHV_CREATE_PARTITION
 42 * @pt_flags: Bitmask of 1 << MSHV_PT_BIT_*
 43 * @pt_isolation: MSHV_PT_ISOLATION_*
 44 *
 45 * This is the initial/v1 version for backward compatibility.
 46 *
 47 * Returns a file descriptor to act as a handle to a guest partition.
 48 * At this point the partition is not yet initialized in the hypervisor.
 49 * Some operations must be done with the partition in this state, e.g. setting
 50 * so-called "early" partition properties. The partition can then be
 51 * initialized with MSHV_INITIALIZE_PARTITION.
 52 */
 53struct mshv_create_partition {
 54	__u64 pt_flags;
 55	__u64 pt_isolation;
 56};
 57
 58#define MSHV_NUM_CPU_FEATURES_BANKS 2
 59
 60/**
 61 * struct mshv_create_partition_v2
 62 *
 63 * This is extended version of the above initial MSHV_CREATE_PARTITION
 64 * ioctl and allows for following additional parameters:
 65 *
 66 * @pt_num_cpu_fbanks: Must be set to MSHV_NUM_CPU_FEATURES_BANKS.
 67 * @pt_cpu_fbanks: Disabled processor feature banks array.
 68 * @pt_disabled_xsave: Disabled xsave feature bits.
 69 *
 70 * pt_cpu_fbanks and pt_disabled_xsave are passed through as-is to the create
 71 * partition hypercall.
 72 *
 73 * Returns : same as above original mshv_create_partition
 74 */
 75struct mshv_create_partition_v2 {
 76	__u64 pt_flags;
 77	__u64 pt_isolation;
 78	__u16 pt_num_cpu_fbanks;
 79	__u8  pt_rsvd[6];		/* MBZ */
 80	__u64 pt_cpu_fbanks[MSHV_NUM_CPU_FEATURES_BANKS];
 81	__u64 pt_rsvd1[2];		/* MBZ */
 82#if defined(__x86_64__)
 83	__u64 pt_disabled_xsave;
 84#else
 85	__u64 pt_rsvd2;			/* MBZ */
 86#endif
 87} __packed;
 88
 89/* /dev/mshv */
 90#define MSHV_CREATE_PARTITION	_IOW(MSHV_IOCTL, 0x00, struct mshv_create_partition)
 91
 92/*
 93 ************************
 94 * Child partition APIs *
 95 ************************
 96 */
 97
 98struct mshv_create_vp {
 99	__u32 vp_index;
100};
101
102enum {
103	MSHV_SET_MEM_BIT_WRITABLE,
104	MSHV_SET_MEM_BIT_EXECUTABLE,
105	MSHV_SET_MEM_BIT_UNMAP,
106	MSHV_SET_MEM_BIT_COUNT
107};
108
109#define MSHV_SET_MEM_FLAGS_MASK ((1 << MSHV_SET_MEM_BIT_COUNT) - 1)
110
111/* The hypervisor's "native" page size */
112#define MSHV_HV_PAGE_SIZE	0x1000
113
114/**
115 * struct mshv_user_mem_region - arguments for MSHV_SET_GUEST_MEMORY
116 * @size: Size of the memory region (bytes). Must be aligned to
117 *        MSHV_HV_PAGE_SIZE
118 * @guest_pfn: Base guest page number to map
119 * @userspace_addr: Base address of userspace memory. Must be aligned to
120 *                  MSHV_HV_PAGE_SIZE
121 * @flags: Bitmask of 1 << MSHV_SET_MEM_BIT_*. If (1 << MSHV_SET_MEM_BIT_UNMAP)
122 *         is set, ignore other bits.
123 * @rsvd: MBZ
124 *
125 * Map or unmap a region of userspace memory to Guest Physical Addresses (GPA).
126 * Mappings can't overlap in GPA space.
127 * To unmap, these fields must match an existing mapping.
128 */
129struct mshv_user_mem_region {
130	__u64 size;
131	__u64 guest_pfn;
132	__u64 userspace_addr;
133	__u8 flags;
134	__u8 rsvd[7];
135};
136
137enum {
138	MSHV_IRQFD_BIT_DEASSIGN,
139	MSHV_IRQFD_BIT_RESAMPLE,
140	MSHV_IRQFD_BIT_COUNT,
141};
142
143#define MSHV_IRQFD_FLAGS_MASK	((1 << MSHV_IRQFD_BIT_COUNT) - 1)
144
145struct mshv_user_irqfd {
146	__s32 fd;
147	__s32 resamplefd;
148	__u32 gsi;
149	__u32 flags;
150};
151
152enum {
153	MSHV_IOEVENTFD_BIT_DATAMATCH,
154	MSHV_IOEVENTFD_BIT_PIO,
155	MSHV_IOEVENTFD_BIT_DEASSIGN,
156	MSHV_IOEVENTFD_BIT_COUNT,
157};
158
159#define MSHV_IOEVENTFD_FLAGS_MASK	((1 << MSHV_IOEVENTFD_BIT_COUNT) - 1)
160
161struct mshv_user_ioeventfd {
162	__u64 datamatch;
163	__u64 addr;	   /* legal pio/mmio address */
164	__u32 len;	   /* 1, 2, 4, or 8 bytes    */
165	__s32 fd;
166	__u32 flags;
167	__u8  rsvd[4];
168};
169
170struct mshv_user_irq_entry {
171	__u32 gsi;
172	__u32 address_lo;
173	__u32 address_hi;
174	__u32 data;
175};
176
177struct mshv_user_irq_table {
178	__u32 nr;
179	__u32 rsvd; /* MBZ */
180	struct mshv_user_irq_entry entries[];
181};
182
183enum {
184	MSHV_GPAP_ACCESS_TYPE_ACCESSED,
185	MSHV_GPAP_ACCESS_TYPE_DIRTY,
186	MSHV_GPAP_ACCESS_TYPE_COUNT		/* Count of enum members */
187};
188
189enum {
190	MSHV_GPAP_ACCESS_OP_NOOP,
191	MSHV_GPAP_ACCESS_OP_CLEAR,
192	MSHV_GPAP_ACCESS_OP_SET,
193	MSHV_GPAP_ACCESS_OP_COUNT		/* Count of enum members */
194};
195
196/**
197 * struct mshv_gpap_access_bitmap - arguments for MSHV_GET_GPAP_ACCESS_BITMAP
198 * @access_type: MSHV_GPAP_ACCESS_TYPE_* - The type of access to record in the
199 *               bitmap
200 * @access_op: MSHV_GPAP_ACCESS_OP_* - Allows an optional clear or set of all
201 *             the access states in the range, after retrieving the current
202 *             states.
203 * @rsvd: MBZ
204 * @page_count: Number of pages
205 * @gpap_base: Base gpa page number
206 * @bitmap_ptr: Output buffer for bitmap, at least (page_count + 7) / 8 bytes
207 *
208 * Retrieve a bitmap of either ACCESSED or DIRTY bits for a given range of guest
209 * memory, and optionally clear or set the bits.
210 */
211struct mshv_gpap_access_bitmap {
212	__u8 access_type;
213	__u8 access_op;
214	__u8 rsvd[6];
215	__u64 page_count;
216	__u64 gpap_base;
217	__u64 bitmap_ptr;
218};
219
220/**
221 * struct mshv_root_hvcall - arguments for MSHV_ROOT_HVCALL
222 * @code: Hypercall code (HVCALL_*)
223 * @reps: in: Rep count ('repcount')
224 *	  out: Reps completed ('repcomp'). MBZ unless rep hvcall
225 * @in_sz: Size of input incl rep data. <= MSHV_HV_PAGE_SIZE
226 * @out_sz: Size of output buffer. <= MSHV_HV_PAGE_SIZE. MBZ if out_ptr is 0
227 * @status: in: MBZ
228 *	    out: HV_STATUS_* from hypercall
229 * @rsvd: MBZ
230 * @in_ptr: Input data buffer (struct hv_input_*). If used with partition or
231 *	    vp fd, partition id field is populated by kernel.
232 * @out_ptr: Output data buffer (optional)
233 */
234struct mshv_root_hvcall {
235	__u16 code;
236	__u16 reps;
237	__u16 in_sz;
238	__u16 out_sz;
239	__u16 status;
240	__u8 rsvd[6];
241	__u64 in_ptr;
242	__u64 out_ptr;
243};
244
245/* Partition fds created with MSHV_CREATE_PARTITION */
246#define MSHV_INITIALIZE_PARTITION	_IO(MSHV_IOCTL, 0x00)
247#define MSHV_CREATE_VP			_IOW(MSHV_IOCTL, 0x01, struct mshv_create_vp)
248#define MSHV_SET_GUEST_MEMORY		_IOW(MSHV_IOCTL, 0x02, struct mshv_user_mem_region)
249#define MSHV_IRQFD			_IOW(MSHV_IOCTL, 0x03, struct mshv_user_irqfd)
250#define MSHV_IOEVENTFD			_IOW(MSHV_IOCTL, 0x04, struct mshv_user_ioeventfd)
251#define MSHV_SET_MSI_ROUTING		_IOW(MSHV_IOCTL, 0x05, struct mshv_user_irq_table)
252#define MSHV_GET_GPAP_ACCESS_BITMAP	_IOWR(MSHV_IOCTL, 0x06, struct mshv_gpap_access_bitmap)
253/* Generic hypercall */
254#define MSHV_ROOT_HVCALL		_IOWR(MSHV_IOCTL, 0x07, struct mshv_root_hvcall)
255
256/*
257 ********************************
258 * VP APIs for child partitions *
259 ********************************
260 */
261
262#define MSHV_RUN_VP_BUF_SZ 256
263
264/*
265 * VP state pages may be mapped to userspace via mmap().
266 * To specify which state page, use MSHV_VP_MMAP_OFFSET_ values multiplied by
267 * the system page size.
268 * e.g.
269 * long page_size = sysconf(_SC_PAGE_SIZE);
270 * void *reg_page = mmap(NULL, MSHV_HV_PAGE_SIZE, PROT_READ|PROT_WRITE,
271 *                       MAP_SHARED, vp_fd,
272 *                       MSHV_VP_MMAP_OFFSET_REGISTERS * page_size);
273 */
274enum {
275	MSHV_VP_MMAP_OFFSET_REGISTERS,
276	MSHV_VP_MMAP_OFFSET_INTERCEPT_MESSAGE,
277	MSHV_VP_MMAP_OFFSET_GHCB,
278	MSHV_VP_MMAP_OFFSET_COUNT
279};
280
281/**
282 * struct mshv_run_vp - argument for MSHV_RUN_VP
283 * @msg_buf: On success, the intercept message is copied here. It can be
284 *           interpreted using the relevant hypervisor definitions.
285 */
286struct mshv_run_vp {
287	__u8 msg_buf[MSHV_RUN_VP_BUF_SZ];
288};
289
290enum {
291	MSHV_VP_STATE_LAPIC,		/* Local interrupt controller state (either arch) */
292	MSHV_VP_STATE_XSAVE,		/* XSAVE data in compacted form (x86_64) */
293	MSHV_VP_STATE_SIMP,
294	MSHV_VP_STATE_SIEFP,
295	MSHV_VP_STATE_SYNTHETIC_TIMERS,
296	MSHV_VP_STATE_COUNT,
297};
298
299/**
300 * struct mshv_get_set_vp_state - arguments for MSHV_[GET,SET]_VP_STATE
301 * @type: MSHV_VP_STATE_*
302 * @rsvd: MBZ
303 * @buf_sz: in: 4k page-aligned size of buffer
304 *          out: Actual size of data (on EINVAL, check this to see if buffer
305 *               was too small)
306 * @buf_ptr: 4k page-aligned data buffer
307 */
308struct mshv_get_set_vp_state {
309	__u8 type;
310	__u8 rsvd[3];
311	__u32 buf_sz;
312	__u64 buf_ptr;
313};
314
315/* VP fds created with MSHV_CREATE_VP */
316#define MSHV_RUN_VP			_IOR(MSHV_IOCTL, 0x00, struct mshv_run_vp)
317#define MSHV_GET_VP_STATE		_IOWR(MSHV_IOCTL, 0x01, struct mshv_get_set_vp_state)
318#define MSHV_SET_VP_STATE		_IOWR(MSHV_IOCTL, 0x02, struct mshv_get_set_vp_state)
319/*
320 * Generic hypercall
321 * Defined above in partition IOCTLs, avoid redefining it here
322 * #define MSHV_ROOT_HVCALL			_IOWR(MSHV_IOCTL, 0x07, struct mshv_root_hvcall)
323 */
324
325/* Structure definitions, macros and IOCTLs for mshv_vtl */
326
327#define MSHV_CAP_CORE_API_STABLE        0x0
328#define MSHV_CAP_REGISTER_PAGE          0x1
329#define MSHV_CAP_VTL_RETURN_ACTION      0x2
330#define MSHV_CAP_DR6_SHARED             0x3
331#define MSHV_MAX_RUN_MSG_SIZE                256
332
333struct mshv_vp_registers {
334	__u32 count;	/* supports only 1 register at a time */
335	__u32 reserved; /* Reserved for alignment or future use */
336	__u64 regs_ptr;	/* pointer to struct hv_register_assoc */
337};
338
339struct mshv_vtl_set_eventfd {
340	__s32 fd;
341	__u32 flag;
342};
343
344struct mshv_vtl_signal_event {
345	__u32 connection_id;
346	__u32 flag;
347};
348
349struct mshv_vtl_sint_post_msg {
350	__u64 message_type;
351	__u32 connection_id;
352	__u32 payload_size; /* Must not exceed HV_MESSAGE_PAYLOAD_BYTE_COUNT */
353	__u64 payload_ptr; /* pointer to message payload (bytes) */
354};
355
356struct mshv_vtl_ram_disposition {
357	__u64 start_pfn;
358	__u64 last_pfn;
359};
360
361struct mshv_vtl_set_poll_file {
362	__u32 cpu;
363	__u32 fd;
364};
365
366struct mshv_vtl_hvcall_setup {
367	__u64 bitmap_array_size; /* stores number of bytes */
368	__u64 allow_bitmap_ptr;
369};
370
371struct mshv_vtl_hvcall {
372	__u64 control;      /* Hypercall control code */
373	__u64 input_size;   /* Size of the input data */
374	__u64 input_ptr;    /* Pointer to the input struct */
375	__u64 status;       /* Status of the hypercall (output) */
376	__u64 output_size;  /* Size of the output data */
377	__u64 output_ptr;   /* Pointer to the output struct */
378};
379
380struct mshv_sint_mask {
381	__u8 mask;
382	__u8 reserved[7];
383};
384
385/* /dev/mshv device IOCTL */
386#define MSHV_CHECK_EXTENSION    _IOW(MSHV_IOCTL, 0x00, __u32)
387
388/* vtl device */
389#define MSHV_CREATE_VTL			_IOR(MSHV_IOCTL, 0x1D, char)
390#define MSHV_ADD_VTL0_MEMORY	_IOW(MSHV_IOCTL, 0x21, struct mshv_vtl_ram_disposition)
391#define MSHV_SET_POLL_FILE		_IOW(MSHV_IOCTL, 0x25, struct mshv_vtl_set_poll_file)
392#define MSHV_RETURN_TO_LOWER_VTL	_IO(MSHV_IOCTL, 0x27)
393#define MSHV_GET_VP_REGISTERS		_IOWR(MSHV_IOCTL, 0x05, struct mshv_vp_registers)
394#define MSHV_SET_VP_REGISTERS		_IOW(MSHV_IOCTL, 0x06, struct mshv_vp_registers)
395
396/* VMBus device IOCTLs */
397#define MSHV_SINT_SIGNAL_EVENT    _IOW(MSHV_IOCTL, 0x22, struct mshv_vtl_signal_event)
398#define MSHV_SINT_POST_MESSAGE    _IOW(MSHV_IOCTL, 0x23, struct mshv_vtl_sint_post_msg)
399#define MSHV_SINT_SET_EVENTFD     _IOW(MSHV_IOCTL, 0x24, struct mshv_vtl_set_eventfd)
400#define MSHV_SINT_PAUSE_MESSAGE_STREAM     _IOW(MSHV_IOCTL, 0x25, struct mshv_sint_mask)
401
402/* hv_hvcall device */
403#define MSHV_HVCALL_SETUP        _IOW(MSHV_IOCTL, 0x1E, struct mshv_vtl_hvcall_setup)
404#define MSHV_HVCALL              _IOWR(MSHV_IOCTL, 0x1F, struct mshv_vtl_hvcall)
405#endif