1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */ 2 /* 3 * Userspace interface for /dev/acrn_hsm - ACRN Hypervisor Service Module 4 * 5 * This file can be used by applications that need to communicate with the HSM 6 * via the ioctl interface. 7 * 8 * Copyright (C) 2021 Intel Corporation. All rights reserved. 9 */ 10 11 #ifndef _UAPI_ACRN_H 12 #define _UAPI_ACRN_H 13 14 #include <linux/types.h> 15 #include <linux/uuid.h> 16 17 #define ACRN_IO_REQUEST_MAX 16 18 19 #define ACRN_IOREQ_STATE_PENDING 0 20 #define ACRN_IOREQ_STATE_COMPLETE 1 21 #define ACRN_IOREQ_STATE_PROCESSING 2 22 #define ACRN_IOREQ_STATE_FREE 3 23 24 #define ACRN_IOREQ_TYPE_PORTIO 0 25 #define ACRN_IOREQ_TYPE_MMIO 1 26 27 #define ACRN_IOREQ_DIR_READ 0 28 #define ACRN_IOREQ_DIR_WRITE 1 29 30 /** 31 * struct acrn_mmio_request - Info of a MMIO I/O request 32 * @direction: Access direction of this request (ACRN_IOREQ_DIR_*) 33 * @reserved: Reserved for alignment and should be 0 34 * @address: Access address of this MMIO I/O request 35 * @size: Access size of this MMIO I/O request 36 * @value: Read/write value of this MMIO I/O request 37 */ 38 struct acrn_mmio_request { 39 __u32 direction; 40 __u32 reserved; 41 __u64 address; 42 __u64 size; 43 __u64 value; 44 }; 45 46 /** 47 * struct acrn_pio_request - Info of a PIO I/O request 48 * @direction: Access direction of this request (ACRN_IOREQ_DIR_*) 49 * @reserved: Reserved for alignment and should be 0 50 * @address: Access address of this PIO I/O request 51 * @size: Access size of this PIO I/O request 52 * @value: Read/write value of this PIO I/O request 53 */ 54 struct acrn_pio_request { 55 __u32 direction; 56 __u32 reserved; 57 __u64 address; 58 __u64 size; 59 __u32 value; 60 }; 61 62 /** 63 * struct acrn_io_request - 256-byte ACRN I/O request 64 * @type: Type of this request (ACRN_IOREQ_TYPE_*). 65 * @completion_polling: Polling flag. Hypervisor will poll completion of the 66 * I/O request if this flag set. 67 * @reserved0: Reserved fields. 68 * @reqs: Union of different types of request. Byte offset: 64. 69 * @reqs.pio_request: PIO request data of the I/O request. 70 * @reqs.mmio_request: MMIO request data of the I/O request. 71 * @reqs.data: Raw data of the I/O request. 72 * @reserved1: Reserved fields. 73 * @kernel_handled: Flag indicates this request need be handled in kernel. 74 * @processed: The status of this request (ACRN_IOREQ_STATE_*). 75 * 76 * The state transitions of ACRN I/O request: 77 * 78 * FREE -> PENDING -> PROCESSING -> COMPLETE -> FREE -> ... 79 * 80 * An I/O request in COMPLETE or FREE state is owned by the hypervisor. HSM and 81 * ACRN userspace are in charge of processing the others. 82 * 83 * On basis of the states illustrated above, a typical lifecycle of ACRN IO 84 * request would look like: 85 * 86 * Flow (assume the initial state is FREE) 87 * | 88 * | Service VM vCPU 0 Service VM vCPU x User vCPU y 89 * | 90 * | hypervisor: 91 * | fills in type, addr, etc. 92 * | pauses the User VM vCPU y 93 * | sets the state to PENDING (a) 94 * | fires an upcall to Service VM 95 * | 96 * | HSM: 97 * | scans for PENDING requests 98 * | sets the states to PROCESSING (b) 99 * | assigns the requests to clients (c) 100 * V 101 * | client: 102 * | scans for the assigned requests 103 * | handles the requests (d) 104 * | HSM: 105 * | sets states to COMPLETE 106 * | notifies the hypervisor 107 * | 108 * | hypervisor: 109 * | resumes User VM vCPU y (e) 110 * | 111 * | hypervisor: 112 * | post handling (f) 113 * V sets states to FREE 114 * 115 * Note that the procedures (a) to (f) in the illustration above require to be 116 * strictly processed in the order. One vCPU cannot trigger another request of 117 * I/O emulation before completing the previous one. 118 * 119 * Atomic and barriers are required when HSM and hypervisor accessing the state 120 * of &struct acrn_io_request. 121 * 122 */ 123 struct acrn_io_request { 124 __u32 type; 125 __u32 completion_polling; 126 __u32 reserved0[14]; 127 union { 128 struct acrn_pio_request pio_request; 129 struct acrn_mmio_request mmio_request; 130 __u64 data[8]; 131 } reqs; 132 __u32 reserved1; 133 __u32 kernel_handled; 134 __u32 processed; 135 } __attribute__((aligned(256))); 136 137 struct acrn_io_request_buffer { 138 union { 139 struct acrn_io_request req_slot[ACRN_IO_REQUEST_MAX]; 140 __u8 reserved[4096]; 141 }; 142 }; 143 144 /** 145 * struct acrn_ioreq_notify - The structure of ioreq completion notification 146 * @vmid: User VM ID 147 * @reserved: Reserved and should be 0 148 * @vcpu: vCPU ID 149 */ 150 struct acrn_ioreq_notify { 151 __u16 vmid; 152 __u16 reserved; 153 __u32 vcpu; 154 }; 155 156 /** 157 * struct acrn_vm_creation - Info to create a User VM 158 * @vmid: User VM ID returned from the hypervisor 159 * @reserved0: Reserved and must be 0 160 * @vcpu_num: Number of vCPU in the VM. Return from hypervisor. 161 * @reserved1: Reserved and must be 0 162 * @uuid: UUID of the VM. Pass to hypervisor directly. 163 * @vm_flag: Flag of the VM creating. Pass to hypervisor directly. 164 * @ioreq_buf: Service VM GPA of I/O request buffer. Pass to 165 * hypervisor directly. 166 * @cpu_affinity: CPU affinity of the VM. Pass to hypervisor directly. 167 * It's a bitmap which indicates CPUs used by the VM. 168 */ 169 struct acrn_vm_creation { 170 __u16 vmid; 171 __u16 reserved0; 172 __u16 vcpu_num; 173 __u16 reserved1; 174 guid_t uuid; 175 __u64 vm_flag; 176 __u64 ioreq_buf; 177 __u64 cpu_affinity; 178 }; 179 180 /** 181 * struct acrn_gp_regs - General registers of a User VM 182 * @rax: Value of register RAX 183 * @rcx: Value of register RCX 184 * @rdx: Value of register RDX 185 * @rbx: Value of register RBX 186 * @rsp: Value of register RSP 187 * @rbp: Value of register RBP 188 * @rsi: Value of register RSI 189 * @rdi: Value of register RDI 190 * @r8: Value of register R8 191 * @r9: Value of register R9 192 * @r10: Value of register R10 193 * @r11: Value of register R11 194 * @r12: Value of register R12 195 * @r13: Value of register R13 196 * @r14: Value of register R14 197 * @r15: Value of register R15 198 */ 199 struct acrn_gp_regs { 200 __le64 rax; 201 __le64 rcx; 202 __le64 rdx; 203 __le64 rbx; 204 __le64 rsp; 205 __le64 rbp; 206 __le64 rsi; 207 __le64 rdi; 208 __le64 r8; 209 __le64 r9; 210 __le64 r10; 211 __le64 r11; 212 __le64 r12; 213 __le64 r13; 214 __le64 r14; 215 __le64 r15; 216 }; 217 218 /** 219 * struct acrn_descriptor_ptr - Segment descriptor table of a User VM. 220 * @limit: Limit field. 221 * @base: Base field. 222 * @reserved: Reserved and must be 0. 223 */ 224 struct acrn_descriptor_ptr { 225 __le16 limit; 226 __le64 base; 227 __le16 reserved[3]; 228 } __attribute__ ((__packed__)); 229 230 /** 231 * struct acrn_regs - Registers structure of a User VM 232 * @gprs: General registers 233 * @gdt: Global Descriptor Table 234 * @idt: Interrupt Descriptor Table 235 * @rip: Value of register RIP 236 * @cs_base: Base of code segment selector 237 * @cr0: Value of register CR0 238 * @cr4: Value of register CR4 239 * @cr3: Value of register CR3 240 * @ia32_efer: Value of IA32_EFER MSR 241 * @rflags: Value of regsiter RFLAGS 242 * @reserved_64: Reserved and must be 0 243 * @cs_ar: Attribute field of code segment selector 244 * @cs_limit: Limit field of code segment selector 245 * @reserved_32: Reserved and must be 0 246 * @cs_sel: Value of code segment selector 247 * @ss_sel: Value of stack segment selector 248 * @ds_sel: Value of data segment selector 249 * @es_sel: Value of extra segment selector 250 * @fs_sel: Value of FS selector 251 * @gs_sel: Value of GS selector 252 * @ldt_sel: Value of LDT descriptor selector 253 * @tr_sel: Value of TSS descriptor selector 254 */ 255 struct acrn_regs { 256 struct acrn_gp_regs gprs; 257 struct acrn_descriptor_ptr gdt; 258 struct acrn_descriptor_ptr idt; 259 260 __le64 rip; 261 __le64 cs_base; 262 __le64 cr0; 263 __le64 cr4; 264 __le64 cr3; 265 __le64 ia32_efer; 266 __le64 rflags; 267 __le64 reserved_64[4]; 268 269 __le32 cs_ar; 270 __le32 cs_limit; 271 __le32 reserved_32[3]; 272 273 __le16 cs_sel; 274 __le16 ss_sel; 275 __le16 ds_sel; 276 __le16 es_sel; 277 __le16 fs_sel; 278 __le16 gs_sel; 279 __le16 ldt_sel; 280 __le16 tr_sel; 281 }; 282 283 /** 284 * struct acrn_vcpu_regs - Info of vCPU registers state 285 * @vcpu_id: vCPU ID 286 * @reserved: Reserved and must be 0 287 * @vcpu_regs: vCPU registers state 288 * 289 * This structure will be passed to hypervisor directly. 290 */ 291 struct acrn_vcpu_regs { 292 __u16 vcpu_id; 293 __u16 reserved[3]; 294 struct acrn_regs vcpu_regs; 295 }; 296 297 #define ACRN_MEM_ACCESS_RIGHT_MASK 0x00000007U 298 #define ACRN_MEM_ACCESS_READ 0x00000001U 299 #define ACRN_MEM_ACCESS_WRITE 0x00000002U 300 #define ACRN_MEM_ACCESS_EXEC 0x00000004U 301 #define ACRN_MEM_ACCESS_RWX (ACRN_MEM_ACCESS_READ | \ 302 ACRN_MEM_ACCESS_WRITE | \ 303 ACRN_MEM_ACCESS_EXEC) 304 305 #define ACRN_MEM_TYPE_MASK 0x000007C0U 306 #define ACRN_MEM_TYPE_WB 0x00000040U 307 #define ACRN_MEM_TYPE_WT 0x00000080U 308 #define ACRN_MEM_TYPE_UC 0x00000100U 309 #define ACRN_MEM_TYPE_WC 0x00000200U 310 #define ACRN_MEM_TYPE_WP 0x00000400U 311 312 /* Memory mapping types */ 313 #define ACRN_MEMMAP_RAM 0 314 #define ACRN_MEMMAP_MMIO 1 315 316 /** 317 * struct acrn_vm_memmap - A EPT memory mapping info for a User VM. 318 * @type: Type of the memory mapping (ACRM_MEMMAP_*). 319 * Pass to hypervisor directly. 320 * @attr: Attribute of the memory mapping. 321 * Pass to hypervisor directly. 322 * @user_vm_pa: Physical address of User VM. 323 * Pass to hypervisor directly. 324 * @service_vm_pa: Physical address of Service VM. 325 * Pass to hypervisor directly. 326 * @vma_base: VMA address of Service VM. Pass to hypervisor directly. 327 * @len: Length of the memory mapping. 328 * Pass to hypervisor directly. 329 */ 330 struct acrn_vm_memmap { 331 __u32 type; 332 __u32 attr; 333 __u64 user_vm_pa; 334 union { 335 __u64 service_vm_pa; 336 __u64 vma_base; 337 }; 338 __u64 len; 339 }; 340 341 /* The ioctl type, documented in ioctl-number.rst */ 342 #define ACRN_IOCTL_TYPE 0xA2 343 344 /* 345 * Common IOCTL IDs definition for ACRN userspace 346 */ 347 #define ACRN_IOCTL_CREATE_VM \ 348 _IOWR(ACRN_IOCTL_TYPE, 0x10, struct acrn_vm_creation) 349 #define ACRN_IOCTL_DESTROY_VM \ 350 _IO(ACRN_IOCTL_TYPE, 0x11) 351 #define ACRN_IOCTL_START_VM \ 352 _IO(ACRN_IOCTL_TYPE, 0x12) 353 #define ACRN_IOCTL_PAUSE_VM \ 354 _IO(ACRN_IOCTL_TYPE, 0x13) 355 #define ACRN_IOCTL_RESET_VM \ 356 _IO(ACRN_IOCTL_TYPE, 0x15) 357 #define ACRN_IOCTL_SET_VCPU_REGS \ 358 _IOW(ACRN_IOCTL_TYPE, 0x16, struct acrn_vcpu_regs) 359 360 #define ACRN_IOCTL_NOTIFY_REQUEST_FINISH \ 361 _IOW(ACRN_IOCTL_TYPE, 0x31, struct acrn_ioreq_notify) 362 #define ACRN_IOCTL_CREATE_IOREQ_CLIENT \ 363 _IO(ACRN_IOCTL_TYPE, 0x32) 364 #define ACRN_IOCTL_ATTACH_IOREQ_CLIENT \ 365 _IO(ACRN_IOCTL_TYPE, 0x33) 366 #define ACRN_IOCTL_DESTROY_IOREQ_CLIENT \ 367 _IO(ACRN_IOCTL_TYPE, 0x34) 368 #define ACRN_IOCTL_CLEAR_VM_IOREQ \ 369 _IO(ACRN_IOCTL_TYPE, 0x35) 370 371 #define ACRN_IOCTL_SET_MEMSEG \ 372 _IOW(ACRN_IOCTL_TYPE, 0x41, struct acrn_vm_memmap) 373 #define ACRN_IOCTL_UNSET_MEMSEG \ 374 _IOW(ACRN_IOCTL_TYPE, 0x42, struct acrn_vm_memmap) 375 376 #endif /* _UAPI_ACRN_H */ 377