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#define ACRN_IOREQ_TYPE_PCICFG 2 27 28#define ACRN_IOREQ_DIR_READ 0 29#define ACRN_IOREQ_DIR_WRITE 1 30 31/** 32 * struct acrn_mmio_request - Info of a MMIO I/O request 33 * @direction: Access direction of this request (ACRN_IOREQ_DIR_*) 34 * @reserved: Reserved for alignment and should be 0 35 * @address: Access address of this MMIO I/O request 36 * @size: Access size of this MMIO I/O request 37 * @value: Read/write value of this MMIO I/O request 38 */ 39struct acrn_mmio_request { 40 __u32 direction; 41 __u32 reserved; 42 __u64 address; 43 __u64 size; 44 __u64 value; 45}; 46 47/** 48 * struct acrn_pio_request - Info of a PIO I/O request 49 * @direction: Access direction of this request (ACRN_IOREQ_DIR_*) 50 * @reserved: Reserved for alignment and should be 0 51 * @address: Access address of this PIO I/O request 52 * @size: Access size of this PIO I/O request 53 * @value: Read/write value of this PIO I/O request 54 */ 55struct acrn_pio_request { 56 __u32 direction; 57 __u32 reserved; 58 __u64 address; 59 __u64 size; 60 __u32 value; 61}; 62 63/** 64 * struct acrn_pci_request - Info of a PCI I/O request 65 * @direction: Access direction of this request (ACRN_IOREQ_DIR_*) 66 * @reserved: Reserved for alignment and should be 0 67 * @size: Access size of this PCI I/O request 68 * @value: Read/write value of this PIO I/O request 69 * @bus: PCI bus value of this PCI I/O request 70 * @dev: PCI device value of this PCI I/O request 71 * @func: PCI function value of this PCI I/O request 72 * @reg: PCI config space offset of this PCI I/O request 73 * 74 * Need keep same header layout with &struct acrn_pio_request. 75 */ 76struct acrn_pci_request { 77 __u32 direction; 78 __u32 reserved[3]; 79 __u64 size; 80 __u32 value; 81 __u32 bus; 82 __u32 dev; 83 __u32 func; 84 __u32 reg; 85}; 86 87/** 88 * struct acrn_io_request - 256-byte ACRN I/O request 89 * @type: Type of this request (ACRN_IOREQ_TYPE_*). 90 * @completion_polling: Polling flag. Hypervisor will poll completion of the 91 * I/O request if this flag set. 92 * @reserved0: Reserved fields. 93 * @reqs: Union of different types of request. Byte offset: 64. 94 * @reqs.pio_request: PIO request data of the I/O request. 95 * @reqs.pci_request: PCI configuration space request data of the I/O request. 96 * @reqs.mmio_request: MMIO request data of the I/O request. 97 * @reqs.data: Raw data of the I/O request. 98 * @reserved1: Reserved fields. 99 * @kernel_handled: Flag indicates this request need be handled in kernel. 100 * @processed: The status of this request (ACRN_IOREQ_STATE_*). 101 * 102 * The state transitions of ACRN I/O request: 103 * 104 * FREE -> PENDING -> PROCESSING -> COMPLETE -> FREE -> ... 105 * 106 * An I/O request in COMPLETE or FREE state is owned by the hypervisor. HSM and 107 * ACRN userspace are in charge of processing the others. 108 * 109 * On basis of the states illustrated above, a typical lifecycle of ACRN IO 110 * request would look like: 111 * 112 * Flow (assume the initial state is FREE) 113 * | 114 * | Service VM vCPU 0 Service VM vCPU x User vCPU y 115 * | 116 * | hypervisor: 117 * | fills in type, addr, etc. 118 * | pauses the User VM vCPU y 119 * | sets the state to PENDING (a) 120 * | fires an upcall to Service VM 121 * | 122 * | HSM: 123 * | scans for PENDING requests 124 * | sets the states to PROCESSING (b) 125 * | assigns the requests to clients (c) 126 * V 127 * | client: 128 * | scans for the assigned requests 129 * | handles the requests (d) 130 * | HSM: 131 * | sets states to COMPLETE 132 * | notifies the hypervisor 133 * | 134 * | hypervisor: 135 * | resumes User VM vCPU y (e) 136 * | 137 * | hypervisor: 138 * | post handling (f) 139 * V sets states to FREE 140 * 141 * Note that the procedures (a) to (f) in the illustration above require to be 142 * strictly processed in the order. One vCPU cannot trigger another request of 143 * I/O emulation before completing the previous one. 144 * 145 * Atomic and barriers are required when HSM and hypervisor accessing the state 146 * of &struct acrn_io_request. 147 * 148 */ 149struct acrn_io_request { 150 __u32 type; 151 __u32 completion_polling; 152 __u32 reserved0[14]; 153 union { 154 struct acrn_pio_request pio_request; 155 struct acrn_pci_request pci_request; 156 struct acrn_mmio_request mmio_request; 157 __u64 data[8]; 158 } reqs; 159 __u32 reserved1; 160 __u32 kernel_handled; 161 __u32 processed; 162} __attribute__((aligned(256))); 163 164struct acrn_io_request_buffer { 165 union { 166 struct acrn_io_request req_slot[ACRN_IO_REQUEST_MAX]; 167 __u8 reserved[4096]; 168 }; 169}; 170 171/** 172 * struct acrn_ioreq_notify - The structure of ioreq completion notification 173 * @vmid: User VM ID 174 * @reserved: Reserved and should be 0 175 * @vcpu: vCPU ID 176 */ 177struct acrn_ioreq_notify { 178 __u16 vmid; 179 __u16 reserved; 180 __u32 vcpu; 181}; 182 183/** 184 * struct acrn_vm_creation - Info to create a User VM 185 * @vmid: User VM ID returned from the hypervisor 186 * @reserved0: Reserved and must be 0 187 * @vcpu_num: Number of vCPU in the VM. Return from hypervisor. 188 * @reserved1: Reserved and must be 0 189 * @uuid: UUID of the VM. Pass to hypervisor directly. 190 * @vm_flag: Flag of the VM creating. Pass to hypervisor directly. 191 * @ioreq_buf: Service VM GPA of I/O request buffer. Pass to 192 * hypervisor directly. 193 * @cpu_affinity: CPU affinity of the VM. Pass to hypervisor directly. 194 * It's a bitmap which indicates CPUs used by the VM. 195 */ 196struct acrn_vm_creation { 197 __u16 vmid; 198 __u16 reserved0; 199 __u16 vcpu_num; 200 __u16 reserved1; 201 guid_t uuid; 202 __u64 vm_flag; 203 __u64 ioreq_buf; 204 __u64 cpu_affinity; 205}; 206 207/** 208 * struct acrn_gp_regs - General registers of a User VM 209 * @rax: Value of register RAX 210 * @rcx: Value of register RCX 211 * @rdx: Value of register RDX 212 * @rbx: Value of register RBX 213 * @rsp: Value of register RSP 214 * @rbp: Value of register RBP 215 * @rsi: Value of register RSI 216 * @rdi: Value of register RDI 217 * @r8: Value of register R8 218 * @r9: Value of register R9 219 * @r10: Value of register R10 220 * @r11: Value of register R11 221 * @r12: Value of register R12 222 * @r13: Value of register R13 223 * @r14: Value of register R14 224 * @r15: Value of register R15 225 */ 226struct acrn_gp_regs { 227 __le64 rax; 228 __le64 rcx; 229 __le64 rdx; 230 __le64 rbx; 231 __le64 rsp; 232 __le64 rbp; 233 __le64 rsi; 234 __le64 rdi; 235 __le64 r8; 236 __le64 r9; 237 __le64 r10; 238 __le64 r11; 239 __le64 r12; 240 __le64 r13; 241 __le64 r14; 242 __le64 r15; 243}; 244 245/** 246 * struct acrn_descriptor_ptr - Segment descriptor table of a User VM. 247 * @limit: Limit field. 248 * @base: Base field. 249 * @reserved: Reserved and must be 0. 250 */ 251struct acrn_descriptor_ptr { 252 __le16 limit; 253 __le64 base; 254 __le16 reserved[3]; 255} __attribute__ ((__packed__)); 256 257/** 258 * struct acrn_regs - Registers structure of a User VM 259 * @gprs: General registers 260 * @gdt: Global Descriptor Table 261 * @idt: Interrupt Descriptor Table 262 * @rip: Value of register RIP 263 * @cs_base: Base of code segment selector 264 * @cr0: Value of register CR0 265 * @cr4: Value of register CR4 266 * @cr3: Value of register CR3 267 * @ia32_efer: Value of IA32_EFER MSR 268 * @rflags: Value of regsiter RFLAGS 269 * @reserved_64: Reserved and must be 0 270 * @cs_ar: Attribute field of code segment selector 271 * @cs_limit: Limit field of code segment selector 272 * @reserved_32: Reserved and must be 0 273 * @cs_sel: Value of code segment selector 274 * @ss_sel: Value of stack segment selector 275 * @ds_sel: Value of data segment selector 276 * @es_sel: Value of extra segment selector 277 * @fs_sel: Value of FS selector 278 * @gs_sel: Value of GS selector 279 * @ldt_sel: Value of LDT descriptor selector 280 * @tr_sel: Value of TSS descriptor selector 281 */ 282struct acrn_regs { 283 struct acrn_gp_regs gprs; 284 struct acrn_descriptor_ptr gdt; 285 struct acrn_descriptor_ptr idt; 286 287 __le64 rip; 288 __le64 cs_base; 289 __le64 cr0; 290 __le64 cr4; 291 __le64 cr3; 292 __le64 ia32_efer; 293 __le64 rflags; 294 __le64 reserved_64[4]; 295 296 __le32 cs_ar; 297 __le32 cs_limit; 298 __le32 reserved_32[3]; 299 300 __le16 cs_sel; 301 __le16 ss_sel; 302 __le16 ds_sel; 303 __le16 es_sel; 304 __le16 fs_sel; 305 __le16 gs_sel; 306 __le16 ldt_sel; 307 __le16 tr_sel; 308}; 309 310/** 311 * struct acrn_vcpu_regs - Info of vCPU registers state 312 * @vcpu_id: vCPU ID 313 * @reserved: Reserved and must be 0 314 * @vcpu_regs: vCPU registers state 315 * 316 * This structure will be passed to hypervisor directly. 317 */ 318struct acrn_vcpu_regs { 319 __u16 vcpu_id; 320 __u16 reserved[3]; 321 struct acrn_regs vcpu_regs; 322}; 323 324#define ACRN_MEM_ACCESS_RIGHT_MASK 0x00000007U 325#define ACRN_MEM_ACCESS_READ 0x00000001U 326#define ACRN_MEM_ACCESS_WRITE 0x00000002U 327#define ACRN_MEM_ACCESS_EXEC 0x00000004U 328#define ACRN_MEM_ACCESS_RWX (ACRN_MEM_ACCESS_READ | \ 329 ACRN_MEM_ACCESS_WRITE | \ 330 ACRN_MEM_ACCESS_EXEC) 331 332#define ACRN_MEM_TYPE_MASK 0x000007C0U 333#define ACRN_MEM_TYPE_WB 0x00000040U 334#define ACRN_MEM_TYPE_WT 0x00000080U 335#define ACRN_MEM_TYPE_UC 0x00000100U 336#define ACRN_MEM_TYPE_WC 0x00000200U 337#define ACRN_MEM_TYPE_WP 0x00000400U 338 339/* Memory mapping types */ 340#define ACRN_MEMMAP_RAM 0 341#define ACRN_MEMMAP_MMIO 1 342 343/** 344 * struct acrn_vm_memmap - A EPT memory mapping info for a User VM. 345 * @type: Type of the memory mapping (ACRM_MEMMAP_*). 346 * Pass to hypervisor directly. 347 * @attr: Attribute of the memory mapping. 348 * Pass to hypervisor directly. 349 * @user_vm_pa: Physical address of User VM. 350 * Pass to hypervisor directly. 351 * @service_vm_pa: Physical address of Service VM. 352 * Pass to hypervisor directly. 353 * @vma_base: VMA address of Service VM. Pass to hypervisor directly. 354 * @len: Length of the memory mapping. 355 * Pass to hypervisor directly. 356 */ 357struct acrn_vm_memmap { 358 __u32 type; 359 __u32 attr; 360 __u64 user_vm_pa; 361 union { 362 __u64 service_vm_pa; 363 __u64 vma_base; 364 }; 365 __u64 len; 366}; 367 368/* Type of interrupt of a passthrough device */ 369#define ACRN_PTDEV_IRQ_INTX 0 370#define ACRN_PTDEV_IRQ_MSI 1 371#define ACRN_PTDEV_IRQ_MSIX 2 372/** 373 * struct acrn_ptdev_irq - Interrupt data of a passthrough device. 374 * @type: Type (ACRN_PTDEV_IRQ_*) 375 * @virt_bdf: Virtual Bus/Device/Function 376 * @phys_bdf: Physical Bus/Device/Function 377 * @intx: Info of interrupt 378 * @intx.virt_pin: Virtual IOAPIC pin 379 * @intx.phys_pin: Physical IOAPIC pin 380 * @intx.is_pic_pin: Is PIC pin or not 381 * 382 * This structure will be passed to hypervisor directly. 383 */ 384struct acrn_ptdev_irq { 385 __u32 type; 386 __u16 virt_bdf; 387 __u16 phys_bdf; 388 389 struct { 390 __u32 virt_pin; 391 __u32 phys_pin; 392 __u32 is_pic_pin; 393 } intx; 394}; 395 396/* Type of PCI device assignment */ 397#define ACRN_PTDEV_QUIRK_ASSIGN (1U << 0) 398 399#define ACRN_PCI_NUM_BARS 6 400/** 401 * struct acrn_pcidev - Info for assigning or de-assigning a PCI device 402 * @type: Type of the assignment 403 * @virt_bdf: Virtual Bus/Device/Function 404 * @phys_bdf: Physical Bus/Device/Function 405 * @intr_line: PCI interrupt line 406 * @intr_pin: PCI interrupt pin 407 * @bar: PCI BARs. 408 * 409 * This structure will be passed to hypervisor directly. 410 */ 411struct acrn_pcidev { 412 __u32 type; 413 __u16 virt_bdf; 414 __u16 phys_bdf; 415 __u8 intr_line; 416 __u8 intr_pin; 417 __u32 bar[ACRN_PCI_NUM_BARS]; 418}; 419 420/** 421 * struct acrn_msi_entry - Info for injecting a MSI interrupt to a VM 422 * @msi_addr: MSI addr[19:12] with dest vCPU ID 423 * @msi_data: MSI data[7:0] with vector 424 */ 425struct acrn_msi_entry { 426 __u64 msi_addr; 427 __u64 msi_data; 428}; 429 430struct acrn_acpi_generic_address { 431 __u8 space_id; 432 __u8 bit_width; 433 __u8 bit_offset; 434 __u8 access_size; 435 __u64 address; 436} __attribute__ ((__packed__)); 437 438/** 439 * struct acrn_cstate_data - A C state package defined in ACPI 440 * @cx_reg: Register of the C state object 441 * @type: Type of the C state object 442 * @latency: The worst-case latency to enter and exit this C state 443 * @power: The average power consumption when in this C state 444 */ 445struct acrn_cstate_data { 446 struct acrn_acpi_generic_address cx_reg; 447 __u8 type; 448 __u32 latency; 449 __u64 power; 450}; 451 452/** 453 * struct acrn_pstate_data - A P state package defined in ACPI 454 * @core_frequency: CPU frequency (in MHz). 455 * @power: Power dissipation (in milliwatts). 456 * @transition_latency: The worst-case latency in microseconds that CPU is 457 * unavailable during a transition from any P state to 458 * this P state. 459 * @bus_master_latency: The worst-case latency in microseconds that Bus Masters 460 * are prevented from accessing memory during a transition 461 * from any P state to this P state. 462 * @control: The value to be written to Performance Control Register 463 * @status: Transition status. 464 */ 465struct acrn_pstate_data { 466 __u64 core_frequency; 467 __u64 power; 468 __u64 transition_latency; 469 __u64 bus_master_latency; 470 __u64 control; 471 __u64 status; 472}; 473 474#define PMCMD_TYPE_MASK 0x000000ff 475enum acrn_pm_cmd_type { 476 ACRN_PMCMD_GET_PX_CNT, 477 ACRN_PMCMD_GET_PX_DATA, 478 ACRN_PMCMD_GET_CX_CNT, 479 ACRN_PMCMD_GET_CX_DATA, 480}; 481 482#define ACRN_IOEVENTFD_FLAG_PIO 0x01 483#define ACRN_IOEVENTFD_FLAG_DATAMATCH 0x02 484#define ACRN_IOEVENTFD_FLAG_DEASSIGN 0x04 485/** 486 * struct acrn_ioeventfd - Data to operate a &struct hsm_ioeventfd 487 * @fd: The fd of eventfd associated with a hsm_ioeventfd 488 * @flags: Logical-OR of ACRN_IOEVENTFD_FLAG_* 489 * @addr: The start address of IO range of ioeventfd 490 * @len: The length of IO range of ioeventfd 491 * @reserved: Reserved and should be 0 492 * @data: Data for data matching 493 * 494 * Without flag ACRN_IOEVENTFD_FLAG_DEASSIGN, ioctl ACRN_IOCTL_IOEVENTFD 495 * creates a &struct hsm_ioeventfd with properties originated from &struct 496 * acrn_ioeventfd. With flag ACRN_IOEVENTFD_FLAG_DEASSIGN, ioctl 497 * ACRN_IOCTL_IOEVENTFD destroys the &struct hsm_ioeventfd matching the fd. 498 */ 499struct acrn_ioeventfd { 500 __u32 fd; 501 __u32 flags; 502 __u64 addr; 503 __u32 len; 504 __u32 reserved; 505 __u64 data; 506}; 507 508#define ACRN_IRQFD_FLAG_DEASSIGN 0x01 509/** 510 * struct acrn_irqfd - Data to operate a &struct hsm_irqfd 511 * @fd: The fd of eventfd associated with a hsm_irqfd 512 * @flags: Logical-OR of ACRN_IRQFD_FLAG_* 513 * @msi: Info of MSI associated with the irqfd 514 */ 515struct acrn_irqfd { 516 __s32 fd; 517 __u32 flags; 518 struct acrn_msi_entry msi; 519}; 520 521/* The ioctl type, documented in ioctl-number.rst */ 522#define ACRN_IOCTL_TYPE 0xA2 523 524/* 525 * Common IOCTL IDs definition for ACRN userspace 526 */ 527#define ACRN_IOCTL_CREATE_VM \ 528 _IOWR(ACRN_IOCTL_TYPE, 0x10, struct acrn_vm_creation) 529#define ACRN_IOCTL_DESTROY_VM \ 530 _IO(ACRN_IOCTL_TYPE, 0x11) 531#define ACRN_IOCTL_START_VM \ 532 _IO(ACRN_IOCTL_TYPE, 0x12) 533#define ACRN_IOCTL_PAUSE_VM \ 534 _IO(ACRN_IOCTL_TYPE, 0x13) 535#define ACRN_IOCTL_RESET_VM \ 536 _IO(ACRN_IOCTL_TYPE, 0x15) 537#define ACRN_IOCTL_SET_VCPU_REGS \ 538 _IOW(ACRN_IOCTL_TYPE, 0x16, struct acrn_vcpu_regs) 539 540#define ACRN_IOCTL_INJECT_MSI \ 541 _IOW(ACRN_IOCTL_TYPE, 0x23, struct acrn_msi_entry) 542#define ACRN_IOCTL_VM_INTR_MONITOR \ 543 _IOW(ACRN_IOCTL_TYPE, 0x24, unsigned long) 544#define ACRN_IOCTL_SET_IRQLINE \ 545 _IOW(ACRN_IOCTL_TYPE, 0x25, __u64) 546 547#define ACRN_IOCTL_NOTIFY_REQUEST_FINISH \ 548 _IOW(ACRN_IOCTL_TYPE, 0x31, struct acrn_ioreq_notify) 549#define ACRN_IOCTL_CREATE_IOREQ_CLIENT \ 550 _IO(ACRN_IOCTL_TYPE, 0x32) 551#define ACRN_IOCTL_ATTACH_IOREQ_CLIENT \ 552 _IO(ACRN_IOCTL_TYPE, 0x33) 553#define ACRN_IOCTL_DESTROY_IOREQ_CLIENT \ 554 _IO(ACRN_IOCTL_TYPE, 0x34) 555#define ACRN_IOCTL_CLEAR_VM_IOREQ \ 556 _IO(ACRN_IOCTL_TYPE, 0x35) 557 558#define ACRN_IOCTL_SET_MEMSEG \ 559 _IOW(ACRN_IOCTL_TYPE, 0x41, struct acrn_vm_memmap) 560#define ACRN_IOCTL_UNSET_MEMSEG \ 561 _IOW(ACRN_IOCTL_TYPE, 0x42, struct acrn_vm_memmap) 562 563#define ACRN_IOCTL_SET_PTDEV_INTR \ 564 _IOW(ACRN_IOCTL_TYPE, 0x53, struct acrn_ptdev_irq) 565#define ACRN_IOCTL_RESET_PTDEV_INTR \ 566 _IOW(ACRN_IOCTL_TYPE, 0x54, struct acrn_ptdev_irq) 567#define ACRN_IOCTL_ASSIGN_PCIDEV \ 568 _IOW(ACRN_IOCTL_TYPE, 0x55, struct acrn_pcidev) 569#define ACRN_IOCTL_DEASSIGN_PCIDEV \ 570 _IOW(ACRN_IOCTL_TYPE, 0x56, struct acrn_pcidev) 571 572#define ACRN_IOCTL_PM_GET_CPU_STATE \ 573 _IOWR(ACRN_IOCTL_TYPE, 0x60, __u64) 574 575#define ACRN_IOCTL_IOEVENTFD \ 576 _IOW(ACRN_IOCTL_TYPE, 0x70, struct acrn_ioeventfd) 577#define ACRN_IOCTL_IRQFD \ 578 _IOW(ACRN_IOCTL_TYPE, 0x71, struct acrn_irqfd) 579 580#endif /* _UAPI_ACRN_H */ 581