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 */ 39 struct acrn_mmio_request { 40 uint32_t direction; 41 uint32_t reserved; 42 uint64_t address; 43 uint64_t size; 44 uint64_t 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 */ 55 struct acrn_pio_request { 56 uint32_t direction; 57 uint32_t reserved; 58 uint64_t address; 59 uint64_t size; 60 uint32_t 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 */ 76 struct acrn_pci_request { 77 uint32_t direction; 78 uint32_t reserved[3]; 79 uint64_t size; 80 uint32_t value; 81 uint32_t bus; 82 uint32_t dev; 83 uint32_t func; 84 uint32_t 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 */ 149 struct acrn_io_request { 150 uint32_t type; 151 uint32_t completion_polling; 152 uint32_t 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 uint64_t data[8]; 158 } reqs; 159 uint32_t reserved1; 160 uint32_t kernel_handled; 161 uint32_t processed; 162 } __attribute__((aligned(256))); 163 164 struct acrn_io_request_buffer { 165 union { 166 struct acrn_io_request req_slot[ACRN_IO_REQUEST_MAX]; 167 uint8_t 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 */ 177 struct acrn_ioreq_notify { 178 uint16_t vmid; 179 uint16_t reserved; 180 uint32_t 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 */ 196 struct acrn_vm_creation { 197 uint16_t vmid; 198 uint16_t reserved0; 199 uint16_t vcpu_num; 200 uint16_t reserved1; 201 guid_t uuid; 202 uint64_t vm_flag; 203 uint64_t ioreq_buf; 204 uint64_t 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 */ 226 struct acrn_gp_regs { 227 uint64_t rax; 228 uint64_t rcx; 229 uint64_t rdx; 230 uint64_t rbx; 231 uint64_t rsp; 232 uint64_t rbp; 233 uint64_t rsi; 234 uint64_t rdi; 235 uint64_t r8; 236 uint64_t r9; 237 uint64_t r10; 238 uint64_t r11; 239 uint64_t r12; 240 uint64_t r13; 241 uint64_t r14; 242 uint64_t 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 */ 251 struct acrn_descriptor_ptr { 252 uint16_t limit; 253 uint64_t base; 254 uint16_t 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 */ 282 struct acrn_regs { 283 struct acrn_gp_regs gprs; 284 struct acrn_descriptor_ptr gdt; 285 struct acrn_descriptor_ptr idt; 286 287 uint64_t rip; 288 uint64_t cs_base; 289 uint64_t cr0; 290 uint64_t cr4; 291 uint64_t cr3; 292 uint64_t ia32_efer; 293 uint64_t rflags; 294 uint64_t reserved_64[4]; 295 296 uint32_t cs_ar; 297 uint32_t cs_limit; 298 uint32_t reserved_32[3]; 299 300 uint16_t cs_sel; 301 uint16_t ss_sel; 302 uint16_t ds_sel; 303 uint16_t es_sel; 304 uint16_t fs_sel; 305 uint16_t gs_sel; 306 uint16_t ldt_sel; 307 uint16_t 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 */ 318 struct acrn_vcpu_regs { 319 uint16_t vcpu_id; 320 uint16_t 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 */ 357 struct acrn_vm_memmap { 358 uint32_t type; 359 uint32_t attr; 360 uint64_t user_vm_pa; 361 union { 362 uint64_t service_vm_pa; 363 uint64_t vma_base; 364 }; 365 uint64_t 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 */ 384 struct acrn_ptdev_irq { 385 uint32_t type; 386 uint16_t virt_bdf; 387 uint16_t phys_bdf; 388 389 struct { 390 uint32_t virt_pin; 391 uint32_t phys_pin; 392 uint32_t 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 */ 411 struct acrn_pcidev { 412 uint32_t type; 413 uint16_t virt_bdf; 414 uint16_t phys_bdf; 415 uint8_t intr_line; 416 uint8_t intr_pin; 417 uint32_t 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 */ 425 struct acrn_msi_entry { 426 uint64_t msi_addr; 427 uint64_t msi_data; 428 }; 429 430 struct acrn_acpi_generic_address { 431 uint8_t space_id; 432 uint8_t bit_width; 433 uint8_t bit_offset; 434 uint8_t access_size; 435 uint64_t 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 */ 445 struct acrn_cstate_data { 446 struct acrn_acpi_generic_address cx_reg; 447 uint8_t type; 448 uint32_t latency; 449 uint64_t 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 */ 465 struct acrn_pstate_data { 466 uint64_t core_frequency; 467 uint64_t power; 468 uint64_t transition_latency; 469 uint64_t bus_master_latency; 470 uint64_t control; 471 uint64_t status; 472 }; 473 474 #define PMCMD_TYPE_MASK 0x000000ff 475 enum 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 */ 499 struct acrn_ioeventfd { 500 uint32_t fd; 501 uint32_t flags; 502 uint64_t addr; 503 uint32_t len; 504 uint32_t reserved; 505 uint64_t 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 */ 515 struct acrn_irqfd { 516 int32_t fd; 517 uint32_t 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, uint64_t) 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, uint64_t) 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