1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
3 * Userspace interface for /dev/acrn_hsm - ACRN Hypervisor Service Module
5 * This file can be used by applications that need to communicate with the HSM
6 * via the ioctl interface.
8 * Copyright (C) 2021 Intel Corporation. All rights reserved.
14 #include <linux/types.h>
15 #include <linux/uuid.h>
17 #define ACRN_IO_REQUEST_MAX 16
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
24 #define ACRN_IOREQ_TYPE_PORTIO 0
25 #define ACRN_IOREQ_TYPE_MMIO 1
26 #define ACRN_IOREQ_TYPE_PCICFG 2
28 #define ACRN_IOREQ_DIR_READ 0
29 #define ACRN_IOREQ_DIR_WRITE 1
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
39 struct acrn_mmio_request {
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
55 struct acrn_pio_request {
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
74 * Need keep same header layout with &struct acrn_pio_request.
76 struct acrn_pci_request {
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_*).
102 * The state transitions of ACRN I/O request:
104 * FREE -> PENDING -> PROCESSING -> COMPLETE -> FREE -> ...
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.
109 * On basis of the states illustrated above, a typical lifecycle of ACRN IO
110 * request would look like:
112 * Flow (assume the initial state is FREE)
114 * | Service VM vCPU 0 Service VM vCPU x User vCPU y
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
123 * | scans for PENDING requests
124 * | sets the states to PROCESSING (b)
125 * | assigns the requests to clients (c)
128 * | scans for the assigned requests
129 * | handles the requests (d)
131 * | sets states to COMPLETE
132 * | notifies the hypervisor
135 * | resumes User VM vCPU y (e)
138 * | post handling (f)
139 * V sets states to FREE
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.
145 * Atomic and barriers are required when HSM and hypervisor accessing the state
146 * of &struct acrn_io_request.
149 struct acrn_io_request {
151 __u32 completion_polling;
154 struct acrn_pio_request pio_request;
155 struct acrn_pci_request pci_request;
156 struct acrn_mmio_request mmio_request;
160 __u32 kernel_handled;
162 } __attribute__((aligned(256)));
164 struct acrn_io_request_buffer {
166 struct acrn_io_request req_slot[ACRN_IO_REQUEST_MAX];
172 * struct acrn_ioreq_notify - The structure of ioreq completion notification
174 * @reserved: Reserved and should be 0
177 struct acrn_ioreq_notify {
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.
196 struct acrn_vm_creation {
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
226 struct acrn_gp_regs {
246 * struct acrn_descriptor_ptr - Segment descriptor table of a User VM.
247 * @limit: Limit field.
249 * @reserved: Reserved and must be 0.
251 struct acrn_descriptor_ptr {
255 } __attribute__ ((__packed__));
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
283 struct acrn_gp_regs gprs;
284 struct acrn_descriptor_ptr gdt;
285 struct acrn_descriptor_ptr idt;
294 __le64 reserved_64[4];
298 __le32 reserved_32[3];
311 * struct acrn_vcpu_regs - Info of vCPU registers state
313 * @reserved: Reserved and must be 0
314 * @vcpu_regs: vCPU registers state
316 * This structure will be passed to hypervisor directly.
318 struct acrn_vcpu_regs {
321 struct acrn_regs vcpu_regs;
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)
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
339 /* Memory mapping types */
340 #define ACRN_MEMMAP_RAM 0
341 #define ACRN_MEMMAP_MMIO 1
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.
357 struct acrn_vm_memmap {
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
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
382 * This structure will be passed to hypervisor directly.
384 struct acrn_ptdev_irq {
396 /* Type of PCI device assignment */
397 #define ACRN_PTDEV_QUIRK_ASSIGN (1U << 0)
399 #define ACRN_MMIODEV_RES_NUM 3
400 #define ACRN_PCI_NUM_BARS 6
402 * struct acrn_pcidev - Info for assigning or de-assigning a PCI device
403 * @type: Type of the assignment
404 * @virt_bdf: Virtual Bus/Device/Function
405 * @phys_bdf: Physical Bus/Device/Function
406 * @intr_line: PCI interrupt line
407 * @intr_pin: PCI interrupt pin
410 * This structure will be passed to hypervisor directly.
418 __u32 bar[ACRN_PCI_NUM_BARS];
422 * struct acrn_mmiodev - Info for assigning or de-assigning a MMIO device
423 * @name: Name of the MMIO device.
424 * @res[].user_vm_pa: Physical address of User VM of the MMIO region
425 * for the MMIO device.
426 * @res[].service_vm_pa: Physical address of Service VM of the MMIO
427 * region for the MMIO device.
428 * @res[].size: Size of the MMIO region for the MMIO device.
429 * @res[].mem_type: Memory type of the MMIO region for the MMIO
432 * This structure will be passed to hypervisor directly.
434 struct acrn_mmiodev {
441 } res[ACRN_MMIODEV_RES_NUM];
445 * struct acrn_vdev - Info for creating or destroying a virtual device
446 * @id: Union of identifier of the virtual device
447 * @id.value: Raw data of the identifier
448 * @id.fields.vendor: Vendor id of the virtual PCI device
449 * @id.fields.device: Device id of the virtual PCI device
450 * @id.fields.legacy_id: ID of the virtual device if not a PCI device
451 * @slot: Virtual Bus/Device/Function of the virtual
453 * @io_base: IO resource base address of the virtual device
454 * @io_size: IO resource size of the virtual device
455 * @args: Arguments for the virtual device creation
457 * The created virtual device can be a PCI device or a legacy device (e.g.
458 * a virtual UART controller) and it is emulated by the hypervisor. This
459 * structure will be passed to hypervisor directly.
463 * the identifier of the device, the low 32 bits represent the vendor
464 * id and device id of PCI device and the high 32 bits represent the
465 * device number of the legacy device
477 __u32 io_addr[ACRN_PCI_NUM_BARS];
478 __u32 io_size[ACRN_PCI_NUM_BARS];
483 * struct acrn_msi_entry - Info for injecting a MSI interrupt to a VM
484 * @msi_addr: MSI addr[19:12] with dest vCPU ID
485 * @msi_data: MSI data[7:0] with vector
487 struct acrn_msi_entry {
492 struct acrn_acpi_generic_address {
498 } __attribute__ ((__packed__));
501 * struct acrn_cstate_data - A C state package defined in ACPI
502 * @cx_reg: Register of the C state object
503 * @type: Type of the C state object
504 * @latency: The worst-case latency to enter and exit this C state
505 * @power: The average power consumption when in this C state
507 struct acrn_cstate_data {
508 struct acrn_acpi_generic_address cx_reg;
515 * struct acrn_pstate_data - A P state package defined in ACPI
516 * @core_frequency: CPU frequency (in MHz).
517 * @power: Power dissipation (in milliwatts).
518 * @transition_latency: The worst-case latency in microseconds that CPU is
519 * unavailable during a transition from any P state to
521 * @bus_master_latency: The worst-case latency in microseconds that Bus Masters
522 * are prevented from accessing memory during a transition
523 * from any P state to this P state.
524 * @control: The value to be written to Performance Control Register
525 * @status: Transition status.
527 struct acrn_pstate_data {
528 __u64 core_frequency;
530 __u64 transition_latency;
531 __u64 bus_master_latency;
536 #define PMCMD_TYPE_MASK 0x000000ff
537 enum acrn_pm_cmd_type {
538 ACRN_PMCMD_GET_PX_CNT,
539 ACRN_PMCMD_GET_PX_DATA,
540 ACRN_PMCMD_GET_CX_CNT,
541 ACRN_PMCMD_GET_CX_DATA,
544 #define ACRN_IOEVENTFD_FLAG_PIO 0x01
545 #define ACRN_IOEVENTFD_FLAG_DATAMATCH 0x02
546 #define ACRN_IOEVENTFD_FLAG_DEASSIGN 0x04
548 * struct acrn_ioeventfd - Data to operate a &struct hsm_ioeventfd
549 * @fd: The fd of eventfd associated with a hsm_ioeventfd
550 * @flags: Logical-OR of ACRN_IOEVENTFD_FLAG_*
551 * @addr: The start address of IO range of ioeventfd
552 * @len: The length of IO range of ioeventfd
553 * @reserved: Reserved and should be 0
554 * @data: Data for data matching
556 * Without flag ACRN_IOEVENTFD_FLAG_DEASSIGN, ioctl ACRN_IOCTL_IOEVENTFD
557 * creates a &struct hsm_ioeventfd with properties originated from &struct
558 * acrn_ioeventfd. With flag ACRN_IOEVENTFD_FLAG_DEASSIGN, ioctl
559 * ACRN_IOCTL_IOEVENTFD destroys the &struct hsm_ioeventfd matching the fd.
561 struct acrn_ioeventfd {
570 #define ACRN_IRQFD_FLAG_DEASSIGN 0x01
572 * struct acrn_irqfd - Data to operate a &struct hsm_irqfd
573 * @fd: The fd of eventfd associated with a hsm_irqfd
574 * @flags: Logical-OR of ACRN_IRQFD_FLAG_*
575 * @msi: Info of MSI associated with the irqfd
580 struct acrn_msi_entry msi;
583 /* The ioctl type, documented in ioctl-number.rst */
584 #define ACRN_IOCTL_TYPE 0xA2
587 * Common IOCTL IDs definition for ACRN userspace
589 #define ACRN_IOCTL_CREATE_VM \
590 _IOWR(ACRN_IOCTL_TYPE, 0x10, struct acrn_vm_creation)
591 #define ACRN_IOCTL_DESTROY_VM \
592 _IO(ACRN_IOCTL_TYPE, 0x11)
593 #define ACRN_IOCTL_START_VM \
594 _IO(ACRN_IOCTL_TYPE, 0x12)
595 #define ACRN_IOCTL_PAUSE_VM \
596 _IO(ACRN_IOCTL_TYPE, 0x13)
597 #define ACRN_IOCTL_RESET_VM \
598 _IO(ACRN_IOCTL_TYPE, 0x15)
599 #define ACRN_IOCTL_SET_VCPU_REGS \
600 _IOW(ACRN_IOCTL_TYPE, 0x16, struct acrn_vcpu_regs)
602 #define ACRN_IOCTL_INJECT_MSI \
603 _IOW(ACRN_IOCTL_TYPE, 0x23, struct acrn_msi_entry)
604 #define ACRN_IOCTL_VM_INTR_MONITOR \
605 _IOW(ACRN_IOCTL_TYPE, 0x24, unsigned long)
606 #define ACRN_IOCTL_SET_IRQLINE \
607 _IOW(ACRN_IOCTL_TYPE, 0x25, __u64)
609 #define ACRN_IOCTL_NOTIFY_REQUEST_FINISH \
610 _IOW(ACRN_IOCTL_TYPE, 0x31, struct acrn_ioreq_notify)
611 #define ACRN_IOCTL_CREATE_IOREQ_CLIENT \
612 _IO(ACRN_IOCTL_TYPE, 0x32)
613 #define ACRN_IOCTL_ATTACH_IOREQ_CLIENT \
614 _IO(ACRN_IOCTL_TYPE, 0x33)
615 #define ACRN_IOCTL_DESTROY_IOREQ_CLIENT \
616 _IO(ACRN_IOCTL_TYPE, 0x34)
617 #define ACRN_IOCTL_CLEAR_VM_IOREQ \
618 _IO(ACRN_IOCTL_TYPE, 0x35)
620 #define ACRN_IOCTL_SET_MEMSEG \
621 _IOW(ACRN_IOCTL_TYPE, 0x41, struct acrn_vm_memmap)
622 #define ACRN_IOCTL_UNSET_MEMSEG \
623 _IOW(ACRN_IOCTL_TYPE, 0x42, struct acrn_vm_memmap)
625 #define ACRN_IOCTL_SET_PTDEV_INTR \
626 _IOW(ACRN_IOCTL_TYPE, 0x53, struct acrn_ptdev_irq)
627 #define ACRN_IOCTL_RESET_PTDEV_INTR \
628 _IOW(ACRN_IOCTL_TYPE, 0x54, struct acrn_ptdev_irq)
629 #define ACRN_IOCTL_ASSIGN_PCIDEV \
630 _IOW(ACRN_IOCTL_TYPE, 0x55, struct acrn_pcidev)
631 #define ACRN_IOCTL_DEASSIGN_PCIDEV \
632 _IOW(ACRN_IOCTL_TYPE, 0x56, struct acrn_pcidev)
633 #define ACRN_IOCTL_ASSIGN_MMIODEV \
634 _IOW(ACRN_IOCTL_TYPE, 0x57, struct acrn_mmiodev)
635 #define ACRN_IOCTL_DEASSIGN_MMIODEV \
636 _IOW(ACRN_IOCTL_TYPE, 0x58, struct acrn_mmiodev)
637 #define ACRN_IOCTL_CREATE_VDEV \
638 _IOW(ACRN_IOCTL_TYPE, 0x59, struct acrn_vdev)
639 #define ACRN_IOCTL_DESTROY_VDEV \
640 _IOW(ACRN_IOCTL_TYPE, 0x5A, struct acrn_vdev)
642 #define ACRN_IOCTL_PM_GET_CPU_STATE \
643 _IOWR(ACRN_IOCTL_TYPE, 0x60, __u64)
645 #define ACRN_IOCTL_IOEVENTFD \
646 _IOW(ACRN_IOCTL_TYPE, 0x70, struct acrn_ioeventfd)
647 #define ACRN_IOCTL_IRQFD \
648 _IOW(ACRN_IOCTL_TYPE, 0x71, struct acrn_irqfd)
650 #endif /* _UAPI_ACRN_H */