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>
16 #define ACRN_IO_REQUEST_MAX 16
18 #define ACRN_IOREQ_STATE_PENDING 0
19 #define ACRN_IOREQ_STATE_COMPLETE 1
20 #define ACRN_IOREQ_STATE_PROCESSING 2
21 #define ACRN_IOREQ_STATE_FREE 3
23 #define ACRN_IOREQ_TYPE_PORTIO 0
24 #define ACRN_IOREQ_TYPE_MMIO 1
25 #define ACRN_IOREQ_TYPE_PCICFG 2
27 #define ACRN_IOREQ_DIR_READ 0
28 #define ACRN_IOREQ_DIR_WRITE 1
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
38 struct acrn_mmio_request
{
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
54 struct acrn_pio_request
{
63 * struct acrn_pci_request - Info of a PCI I/O request
64 * @direction: Access direction of this request (ACRN_IOREQ_DIR_*)
65 * @reserved: Reserved for alignment and should be 0
66 * @size: Access size of this PCI I/O request
67 * @value: Read/write value of this PIO I/O request
68 * @bus: PCI bus value of this PCI I/O request
69 * @dev: PCI device value of this PCI I/O request
70 * @func: PCI function value of this PCI I/O request
71 * @reg: PCI config space offset of this PCI I/O request
73 * Need keep same header layout with &struct acrn_pio_request.
75 struct acrn_pci_request
{
87 * struct acrn_io_request - 256-byte ACRN I/O request
88 * @type: Type of this request (ACRN_IOREQ_TYPE_*).
89 * @completion_polling: Polling flag. Hypervisor will poll completion of the
90 * I/O request if this flag set.
91 * @reserved0: Reserved fields.
92 * @reqs: Union of different types of request. Byte offset: 64.
93 * @reqs.pio_request: PIO request data of the I/O request.
94 * @reqs.pci_request: PCI configuration space request data of the I/O request.
95 * @reqs.mmio_request: MMIO request data of the I/O request.
96 * @reqs.data: Raw data of the I/O request.
97 * @reserved1: Reserved fields.
98 * @kernel_handled: Flag indicates this request need be handled in kernel.
99 * @processed: The status of this request (ACRN_IOREQ_STATE_*).
101 * The state transitions of ACRN I/O request:
103 * FREE -> PENDING -> PROCESSING -> COMPLETE -> FREE -> ...
105 * An I/O request in COMPLETE or FREE state is owned by the hypervisor. HSM and
106 * ACRN userspace are in charge of processing the others.
108 * On basis of the states illustrated above, a typical lifecycle of ACRN IO
109 * request would look like:
111 * Flow (assume the initial state is FREE)
113 * | Service VM vCPU 0 Service VM vCPU x User vCPU y
116 * | fills in type, addr, etc.
117 * | pauses the User VM vCPU y
118 * | sets the state to PENDING (a)
119 * | fires an upcall to Service VM
122 * | scans for PENDING requests
123 * | sets the states to PROCESSING (b)
124 * | assigns the requests to clients (c)
127 * | scans for the assigned requests
128 * | handles the requests (d)
130 * | sets states to COMPLETE
131 * | notifies the hypervisor
134 * | resumes User VM vCPU y (e)
137 * | post handling (f)
138 * V sets states to FREE
140 * Note that the procedures (a) to (f) in the illustration above require to be
141 * strictly processed in the order. One vCPU cannot trigger another request of
142 * I/O emulation before completing the previous one.
144 * Atomic and barriers are required when HSM and hypervisor accessing the state
145 * of &struct acrn_io_request.
148 struct acrn_io_request
{
150 __u32 completion_polling
;
153 struct acrn_pio_request pio_request
;
154 struct acrn_pci_request pci_request
;
155 struct acrn_mmio_request mmio_request
;
159 __u32 kernel_handled
;
161 } __attribute__((aligned(256)));
163 struct acrn_io_request_buffer
{
165 struct acrn_io_request req_slot
[ACRN_IO_REQUEST_MAX
];
171 * struct acrn_ioreq_notify - The structure of ioreq completion notification
173 * @reserved: Reserved and should be 0
176 struct acrn_ioreq_notify
{
183 * struct acrn_vm_creation - Info to create a User VM
184 * @vmid: User VM ID returned from the hypervisor
185 * @reserved0: Reserved and must be 0
186 * @vcpu_num: Number of vCPU in the VM. Return from hypervisor.
187 * @reserved1: Reserved and must be 0
188 * @uuid: Empty space never to be used again (used to be UUID of the VM)
189 * @vm_flag: Flag of the VM creating. Pass to hypervisor directly.
190 * @ioreq_buf: Service VM GPA of I/O request buffer. Pass to
191 * hypervisor directly.
192 * @cpu_affinity: CPU affinity of the VM. Pass to hypervisor directly.
193 * It's a bitmap which indicates CPUs used by the VM.
195 struct acrn_vm_creation
{
207 * struct acrn_gp_regs - General registers of a User VM
208 * @rax: Value of register RAX
209 * @rcx: Value of register RCX
210 * @rdx: Value of register RDX
211 * @rbx: Value of register RBX
212 * @rsp: Value of register RSP
213 * @rbp: Value of register RBP
214 * @rsi: Value of register RSI
215 * @rdi: Value of register RDI
216 * @r8: Value of register R8
217 * @r9: Value of register R9
218 * @r10: Value of register R10
219 * @r11: Value of register R11
220 * @r12: Value of register R12
221 * @r13: Value of register R13
222 * @r14: Value of register R14
223 * @r15: Value of register R15
225 struct acrn_gp_regs
{
245 * struct acrn_descriptor_ptr - Segment descriptor table of a User VM.
246 * @limit: Limit field.
248 * @reserved: Reserved and must be 0.
250 struct acrn_descriptor_ptr
{
254 } __attribute__ ((__packed__
));
257 * struct acrn_regs - Registers structure of a User VM
258 * @gprs: General registers
259 * @gdt: Global Descriptor Table
260 * @idt: Interrupt Descriptor Table
261 * @rip: Value of register RIP
262 * @cs_base: Base of code segment selector
263 * @cr0: Value of register CR0
264 * @cr4: Value of register CR4
265 * @cr3: Value of register CR3
266 * @ia32_efer: Value of IA32_EFER MSR
267 * @rflags: Value of regsiter RFLAGS
268 * @reserved_64: Reserved and must be 0
269 * @cs_ar: Attribute field of code segment selector
270 * @cs_limit: Limit field of code segment selector
271 * @reserved_32: Reserved and must be 0
272 * @cs_sel: Value of code segment selector
273 * @ss_sel: Value of stack segment selector
274 * @ds_sel: Value of data segment selector
275 * @es_sel: Value of extra segment selector
276 * @fs_sel: Value of FS selector
277 * @gs_sel: Value of GS selector
278 * @ldt_sel: Value of LDT descriptor selector
279 * @tr_sel: Value of TSS descriptor selector
282 struct acrn_gp_regs gprs
;
283 struct acrn_descriptor_ptr gdt
;
284 struct acrn_descriptor_ptr idt
;
293 __le64 reserved_64
[4];
297 __le32 reserved_32
[3];
310 * struct acrn_vcpu_regs - Info of vCPU registers state
312 * @reserved: Reserved and must be 0
313 * @vcpu_regs: vCPU registers state
315 * This structure will be passed to hypervisor directly.
317 struct acrn_vcpu_regs
{
320 struct acrn_regs vcpu_regs
;
323 #define ACRN_MEM_ACCESS_RIGHT_MASK 0x00000007U
324 #define ACRN_MEM_ACCESS_READ 0x00000001U
325 #define ACRN_MEM_ACCESS_WRITE 0x00000002U
326 #define ACRN_MEM_ACCESS_EXEC 0x00000004U
327 #define ACRN_MEM_ACCESS_RWX (ACRN_MEM_ACCESS_READ | \
328 ACRN_MEM_ACCESS_WRITE | \
329 ACRN_MEM_ACCESS_EXEC)
331 #define ACRN_MEM_TYPE_MASK 0x000007C0U
332 #define ACRN_MEM_TYPE_WB 0x00000040U
333 #define ACRN_MEM_TYPE_WT 0x00000080U
334 #define ACRN_MEM_TYPE_UC 0x00000100U
335 #define ACRN_MEM_TYPE_WC 0x00000200U
336 #define ACRN_MEM_TYPE_WP 0x00000400U
338 /* Memory mapping types */
339 #define ACRN_MEMMAP_RAM 0
340 #define ACRN_MEMMAP_MMIO 1
343 * struct acrn_vm_memmap - A EPT memory mapping info for a User VM.
344 * @type: Type of the memory mapping (ACRM_MEMMAP_*).
345 * Pass to hypervisor directly.
346 * @attr: Attribute of the memory mapping.
347 * Pass to hypervisor directly.
348 * @user_vm_pa: Physical address of User VM.
349 * Pass to hypervisor directly.
350 * @service_vm_pa: Physical address of Service VM.
351 * Pass to hypervisor directly.
352 * @vma_base: VMA address of Service VM. Pass to hypervisor directly.
353 * @len: Length of the memory mapping.
354 * Pass to hypervisor directly.
356 struct acrn_vm_memmap
{
367 /* Type of interrupt of a passthrough device */
368 #define ACRN_PTDEV_IRQ_INTX 0
369 #define ACRN_PTDEV_IRQ_MSI 1
370 #define ACRN_PTDEV_IRQ_MSIX 2
372 * struct acrn_ptdev_irq - Interrupt data of a passthrough device.
373 * @type: Type (ACRN_PTDEV_IRQ_*)
374 * @virt_bdf: Virtual Bus/Device/Function
375 * @phys_bdf: Physical Bus/Device/Function
376 * @intx: Info of interrupt
377 * @intx.virt_pin: Virtual IOAPIC pin
378 * @intx.phys_pin: Physical IOAPIC pin
379 * @intx.is_pic_pin: Is PIC pin or not
381 * This structure will be passed to hypervisor directly.
383 struct acrn_ptdev_irq
{
395 /* Type of PCI device assignment */
396 #define ACRN_PTDEV_QUIRK_ASSIGN (1U << 0)
398 #define ACRN_MMIODEV_RES_NUM 3
399 #define ACRN_PCI_NUM_BARS 6
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
409 * This structure will be passed to hypervisor directly.
417 __u32 bar
[ACRN_PCI_NUM_BARS
];
421 * struct acrn_mmiodev - Info for assigning or de-assigning a MMIO device
422 * @name: Name of the MMIO device.
423 * @res[].user_vm_pa: Physical address of User VM of the MMIO region
424 * for the MMIO device.
425 * @res[].service_vm_pa: Physical address of Service VM of the MMIO
426 * region for the MMIO device.
427 * @res[].size: Size of the MMIO region for the MMIO device.
428 * @res[].mem_type: Memory type of the MMIO region for the MMIO
431 * This structure will be passed to hypervisor directly.
433 struct acrn_mmiodev
{
440 } res
[ACRN_MMIODEV_RES_NUM
];
444 * struct acrn_vdev - Info for creating or destroying a virtual device
445 * @id: Union of identifier of the virtual device
446 * @id.value: Raw data of the identifier
447 * @id.fields.vendor: Vendor id of the virtual PCI device
448 * @id.fields.device: Device id of the virtual PCI device
449 * @id.fields.legacy_id: ID of the virtual device if not a PCI device
450 * @slot: Virtual Bus/Device/Function of the virtual
452 * @io_base: IO resource base address of the virtual device
453 * @io_size: IO resource size of the virtual device
454 * @args: Arguments for the virtual device creation
456 * The created virtual device can be a PCI device or a legacy device (e.g.
457 * a virtual UART controller) and it is emulated by the hypervisor. This
458 * structure will be passed to hypervisor directly.
462 * the identifier of the device, the low 32 bits represent the vendor
463 * id and device id of PCI device and the high 32 bits represent the
464 * device number of the legacy device
476 __u32 io_addr
[ACRN_PCI_NUM_BARS
];
477 __u32 io_size
[ACRN_PCI_NUM_BARS
];
482 * struct acrn_msi_entry - Info for injecting a MSI interrupt to a VM
483 * @msi_addr: MSI addr[19:12] with dest vCPU ID
484 * @msi_data: MSI data[7:0] with vector
486 struct acrn_msi_entry
{
491 struct acrn_acpi_generic_address
{
497 } __attribute__ ((__packed__
));
500 * struct acrn_cstate_data - A C state package defined in ACPI
501 * @cx_reg: Register of the C state object
502 * @type: Type of the C state object
503 * @latency: The worst-case latency to enter and exit this C state
504 * @power: The average power consumption when in this C state
506 struct acrn_cstate_data
{
507 struct acrn_acpi_generic_address cx_reg
;
514 * struct acrn_pstate_data - A P state package defined in ACPI
515 * @core_frequency: CPU frequency (in MHz).
516 * @power: Power dissipation (in milliwatts).
517 * @transition_latency: The worst-case latency in microseconds that CPU is
518 * unavailable during a transition from any P state to
520 * @bus_master_latency: The worst-case latency in microseconds that Bus Masters
521 * are prevented from accessing memory during a transition
522 * from any P state to this P state.
523 * @control: The value to be written to Performance Control Register
524 * @status: Transition status.
526 struct acrn_pstate_data
{
527 __u64 core_frequency
;
529 __u64 transition_latency
;
530 __u64 bus_master_latency
;
535 #define PMCMD_TYPE_MASK 0x000000ff
536 enum acrn_pm_cmd_type
{
537 ACRN_PMCMD_GET_PX_CNT
,
538 ACRN_PMCMD_GET_PX_DATA
,
539 ACRN_PMCMD_GET_CX_CNT
,
540 ACRN_PMCMD_GET_CX_DATA
,
543 #define ACRN_IOEVENTFD_FLAG_PIO 0x01
544 #define ACRN_IOEVENTFD_FLAG_DATAMATCH 0x02
545 #define ACRN_IOEVENTFD_FLAG_DEASSIGN 0x04
547 * struct acrn_ioeventfd - Data to operate a &struct hsm_ioeventfd
548 * @fd: The fd of eventfd associated with a hsm_ioeventfd
549 * @flags: Logical-OR of ACRN_IOEVENTFD_FLAG_*
550 * @addr: The start address of IO range of ioeventfd
551 * @len: The length of IO range of ioeventfd
552 * @reserved: Reserved and should be 0
553 * @data: Data for data matching
555 * Without flag ACRN_IOEVENTFD_FLAG_DEASSIGN, ioctl ACRN_IOCTL_IOEVENTFD
556 * creates a &struct hsm_ioeventfd with properties originated from &struct
557 * acrn_ioeventfd. With flag ACRN_IOEVENTFD_FLAG_DEASSIGN, ioctl
558 * ACRN_IOCTL_IOEVENTFD destroys the &struct hsm_ioeventfd matching the fd.
560 struct acrn_ioeventfd
{
569 #define ACRN_IRQFD_FLAG_DEASSIGN 0x01
571 * struct acrn_irqfd - Data to operate a &struct hsm_irqfd
572 * @fd: The fd of eventfd associated with a hsm_irqfd
573 * @flags: Logical-OR of ACRN_IRQFD_FLAG_*
574 * @msi: Info of MSI associated with the irqfd
579 struct acrn_msi_entry msi
;
582 /* The ioctl type, documented in ioctl-number.rst */
583 #define ACRN_IOCTL_TYPE 0xA2
586 * Common IOCTL IDs definition for ACRN userspace
588 #define ACRN_IOCTL_CREATE_VM \
589 _IOWR(ACRN_IOCTL_TYPE, 0x10, struct acrn_vm_creation)
590 #define ACRN_IOCTL_DESTROY_VM \
591 _IO(ACRN_IOCTL_TYPE, 0x11)
592 #define ACRN_IOCTL_START_VM \
593 _IO(ACRN_IOCTL_TYPE, 0x12)
594 #define ACRN_IOCTL_PAUSE_VM \
595 _IO(ACRN_IOCTL_TYPE, 0x13)
596 #define ACRN_IOCTL_RESET_VM \
597 _IO(ACRN_IOCTL_TYPE, 0x15)
598 #define ACRN_IOCTL_SET_VCPU_REGS \
599 _IOW(ACRN_IOCTL_TYPE, 0x16, struct acrn_vcpu_regs)
601 #define ACRN_IOCTL_INJECT_MSI \
602 _IOW(ACRN_IOCTL_TYPE, 0x23, struct acrn_msi_entry)
603 #define ACRN_IOCTL_VM_INTR_MONITOR \
604 _IOW(ACRN_IOCTL_TYPE, 0x24, unsigned long)
605 #define ACRN_IOCTL_SET_IRQLINE \
606 _IOW(ACRN_IOCTL_TYPE, 0x25, __u64)
608 #define ACRN_IOCTL_NOTIFY_REQUEST_FINISH \
609 _IOW(ACRN_IOCTL_TYPE, 0x31, struct acrn_ioreq_notify)
610 #define ACRN_IOCTL_CREATE_IOREQ_CLIENT \
611 _IO(ACRN_IOCTL_TYPE, 0x32)
612 #define ACRN_IOCTL_ATTACH_IOREQ_CLIENT \
613 _IO(ACRN_IOCTL_TYPE, 0x33)
614 #define ACRN_IOCTL_DESTROY_IOREQ_CLIENT \
615 _IO(ACRN_IOCTL_TYPE, 0x34)
616 #define ACRN_IOCTL_CLEAR_VM_IOREQ \
617 _IO(ACRN_IOCTL_TYPE, 0x35)
619 #define ACRN_IOCTL_SET_MEMSEG \
620 _IOW(ACRN_IOCTL_TYPE, 0x41, struct acrn_vm_memmap)
621 #define ACRN_IOCTL_UNSET_MEMSEG \
622 _IOW(ACRN_IOCTL_TYPE, 0x42, struct acrn_vm_memmap)
624 #define ACRN_IOCTL_SET_PTDEV_INTR \
625 _IOW(ACRN_IOCTL_TYPE, 0x53, struct acrn_ptdev_irq)
626 #define ACRN_IOCTL_RESET_PTDEV_INTR \
627 _IOW(ACRN_IOCTL_TYPE, 0x54, struct acrn_ptdev_irq)
628 #define ACRN_IOCTL_ASSIGN_PCIDEV \
629 _IOW(ACRN_IOCTL_TYPE, 0x55, struct acrn_pcidev)
630 #define ACRN_IOCTL_DEASSIGN_PCIDEV \
631 _IOW(ACRN_IOCTL_TYPE, 0x56, struct acrn_pcidev)
632 #define ACRN_IOCTL_ASSIGN_MMIODEV \
633 _IOW(ACRN_IOCTL_TYPE, 0x57, struct acrn_mmiodev)
634 #define ACRN_IOCTL_DEASSIGN_MMIODEV \
635 _IOW(ACRN_IOCTL_TYPE, 0x58, struct acrn_mmiodev)
636 #define ACRN_IOCTL_CREATE_VDEV \
637 _IOW(ACRN_IOCTL_TYPE, 0x59, struct acrn_vdev)
638 #define ACRN_IOCTL_DESTROY_VDEV \
639 _IOW(ACRN_IOCTL_TYPE, 0x5A, struct acrn_vdev)
641 #define ACRN_IOCTL_PM_GET_CPU_STATE \
642 _IOWR(ACRN_IOCTL_TYPE, 0x60, __u64)
644 #define ACRN_IOCTL_IOEVENTFD \
645 _IOW(ACRN_IOCTL_TYPE, 0x70, struct acrn_ioeventfd)
646 #define ACRN_IOCTL_IRQFD \
647 _IOW(ACRN_IOCTL_TYPE, 0x71, struct acrn_irqfd)
649 #endif /* _UAPI_ACRN_H */